Festival: A Vibe Engineering Framework

wpnews.pro

Festival is a vibe engineering framework.

You configure it to your specific workflows and processes. When it plans and executes, the work is done the way you want it done.

You describe a goal in a sentence. Your agent plans that goal inside the workflows you set up, and fest next runs the next step. The plan, the checks, and the commits stay in files and Git when the session ends.

A camp is where that configuration lives. A festival is one long goal inside it. Use it with Claude Code, Codex, Grok Build, Cursor, OpenCode, or another agent that can read files and run commands.

Get started · Explore the demos · Video quick start · Website · Discord · 简体中文

Three completed festivals built the CodeSignal Practice Simulator. Agents followed the fest next loop, with testing and review gates feeding findings back into fixes. The demo repository includes the plans, tasks, review findings, and verification evidence for each build.

Explore the demo · Inspect the three festivals · Watch all three replays

Try your own handoff, or star this repository to keep it handy.

Start with a real outcome that you can review. For example:

A feature across repositories: “Add account deletion to the API and web app. Cover it with tests and document how existing users are affected.”
An investigation before a build: “Investigate why this service slows down under load. Save the evidence, compare the options, and bring me a recommendation before changing production.”
A recurring review: “Review this week's dependency changes, flag compatibility risks, and prepare the updates for my approval.”

The goal, constraints, and success criteria come from you. Your agent works through the plan and returns when it reaches a review point or a decision that needs you.

Explore the use cases · See example camps and festivals

Choose one method. Both install camp, fest, and the festival manager. Git is required.

macOS with Homebrew

brew install --cask Obedience-Corp/tap/festival

macOS or Linux with Node.js

npm install -g @obedience-corp/festival

Then check the install:

festival doctor

Linux packages, WSL2, and other install methods. Native Windows support is being hardened; use WSL2 for now.

A camp holds the context for one part of your life: your job, a side project, or a hobby. It can contain several projects, along with their research, plans, and decisions.

After installing, create a camp:

camp create my-camp
camp create work
csw my-camp
csw work

camp create puts each camp in ~/campaigns/ and asks for a description and mission. csw is the shorthand for camp switch and moves your shell from one camp to the other. Add the shell integration so the shorthand exists. With no name, csw opens the picker.

One recording, in a fresh demo home. On your machine the camps are at ~/campaigns/my-camp and ~/campaigns/work.

If an agent is already open, paste this. It installs Festival when camp is missing, updates camp, fest, and festival together, creates the camp, and adds the shell hook. Open a new terminal and run csw <name> to enter the camp.

If `camp` is missing, install Festival, then run `festival doctor`. On macOS with Homebrew, use `brew install --cask Obedience-Corp/tap/festival`. On macOS or Linux with Node.js, use `npm install -g @obedience-corp/festival`.

To update camp, fest, and festival together, run `festival update`. Do not pass `--force`.

Ask me for a camp name, a one-line description, and a mission. Create the camp with `camp create <name> -d "<description>" -m "<mission>"`. The camp is at `~/campaigns/<name>`. Read `camp create --help` before adding flags. Use `camp create` for this. Do not run `camp init` or `festival setup`.

After Festival is installed, add the shell hook with the installer. Detect my shell and run one of `festival shell-init zsh --append --yes`, `festival shell-init bash --append --yes`, or `festival shell-init fish --append --yes`. Pass `--yes`. Without it, and with no terminal to answer, the installer writes nothing. The command skips the edit when the hook is already there. Then tell me to open a new terminal and run `csw <name>`. You can keep working in `~/campaigns/<name>`.

Skills are optional. The CLI can teach you the workflow.

Open your coding agent at that camp root. The agent setup guides cover skills and integrations for your tool. Skills are optional; the CLI can teach your agent the workflow.

Link a repository you already use. Replace the path with its full local path:

camp project link /path/to/your-existing-repo

Your repository stays where it is. Camp links it under projects/ and adds a .camp attachment file to the repository. You can also clone a project into the camp.

A festival is the structured plan and work record for a goal. Tell your agent what you want done and ask it to create a festival for the work:

I want [what you want done]. Create a festival for it and run the fest next loop.

A real Grok Build session planning a sample app feature. The agent handles the planning commands; you review the proposed work.

Your agent handles planning and execution, asking you when it reaches an approval point or needs a decision. You can focus on other work and review the results when they're ready.

To check progress along the way, open another terminal in the festival directory and run fest watch.

The progress view you can open alongside your agent. This recording demonstrates the real fest watch interface with scripted progress updates in a sample festival.

If the session ends: point your next agent at the saved festival and ask it to continue from the linked project. The recorded plan, progress, and decisions give it a starting point.

Follow the video quick start to see setup, planning with Grok Build, and the progress view.

fest gif turns recorded festival progress into a GIF you can send and share:

fest gif my-festival -o replay.gif
fest gif --festival MF0001 --speed 2

When a festival moves to completed, Fest creates festival-replay.gif and embeds it in FESTIVAL_OVERVIEW.md, with both files included in the completion commit. Use fest gif --embed to refresh it or add a replay to an older festival.

See the replay guide for examples, sharing, and recovery.

A festival is a graph of work, organized into phases, sequences, and tasks. Each task has context and completion criteria. Your agent uses fest next to find the next actionable step, does the work, checks the result, and records progress before continuing.

That is the basis for loop engineering with Festival: repeatable planning, execution, review, and handoff loops. You can start with a lightweight WORKFLOW.md, build a full festival for a larger goal, or run separate festivals with agents in separate worktrees.

The camp holds the context around those goals over the life of the work. Research can inform a design; that design can become a festival; its results and decisions remain available for the next goal.

Quality gates provide places to test and review. fest validate checks plan structure, and fest commit links commits to festival tasks. You review the actual output and verification evidence before accepting the result.

Loops & orchestration · Festival methodology · Work items

Tool	What it handles
camp	Projects, context, navigation, and the work queue across your camp.
fest	Goal-based plans, the next-step loop, progress, and review checkpoints.
`festival`	Installing and updating the suite, browsing CLI plugins, and checking your installation.

Run festival browse to explore available CLI plugins. See suite and plugin management for installation, updates, and how CLI plugins differ from agent integrations.

Jump straight to the work.cgo p api finds a matching project;cgo f takes you to festivals. Add theshell integration to enable these shortcuts.
Switch camps.camp switch moves between registered camps.csw is the shorthand.
Find the next thing to pick up.camp workitem brings intents, research, designs, and festivals into one work queue.
Start fresh after a merged PR.camp fresh syncs a project to its default branch and prunes merged branches. Preview withcamp fresh --dry-run from that project first, including any configured branch creation or follow-up commands.

Everyday development with cgo and camp fresh

The GIFs play on this page at a readable size.

Move between projects, plans, and camps #

cgo jumps to a project or planning directory. camp switch moves between camps, and csw is the shorthand.

See your camps and the projects inside one #

camp list browses registered camps by org. Move through them, change a camp's status, and filter down to the active ones.

camp project list browses the projects in the current camp, grouped by type.

Find work, capture an idea, and sort the inbox #

Find work across the camp. camp workitem brings intents, research, designs, and festivals into one searchable list.

Capture an idea. camp intent add saves it to the inbox for later.

Sort the inbox. camp intent explore lets you browse intents by status and read their details.

See which festivals are active and inspect a plan #

fest list groups festivals by status, so you can see what's active, ready, or still being planned.

fest show opens the structure of a plan, from its phases down to individual tasks.

Start fresh after a merged change #

camp fresh configure sets the follow-up commands that run after a project syncs.

camp fresh checks out the default branch, pulls, prunes merged branches, and runs those follow-ups.

Add testing and review gates to a plan #

fest gates apply previews the quality gates it will add before applying them with approval.

Review old work and clear space for what's next #

camp dungeon crawl walks through stale work so you can choose what to keep or archive.

Reach a camp on another machine #

camp machine lists computers camp can hop to, and can add one from your Tailscale network.

Open the Festival installer #

festival opens the suite manager: install the tools, check the setup, and launch camp and fest.

Watch a longer Festival session (click to expand video preview) #

An earlier Festival workflow recording at 16× playback speed. Use the setup instructions above for the current first-run path.