Festival

Festival is a vibe engineering framework.

It uses the filesystem and Git. You configure it to your workflows and processes. When agents plan and executes, the work is done the way you want it done.

Everything lives in a camp workspace: your skills, planning documents, one-off scripts, and projects. A festival is an ambitious goal inside that camp. Specs, smaller workflows, and ideas you intend to execute are tracked as work items.

You can create as many camps as you need and specialize each with its own skills, workflows, and processes. As you refine them over time, agents work differently in each camp. Switch between camps with camp switch (csw) to pick up that workspace's context and way of working.

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.

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 · 简体中文

See Festival in action

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.

What would you hand off?

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

Get started

1. Install

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.

2. Make a camp for your work

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.

3. Give your agent a goal

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.

4. Follow progress and review the result

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.

Share a festival replay

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.

Why I built Festival

I was working with agents at scale, and the bottleneck moved from doing the work to reviewing, understanding, and tracking it. That was draining the time I wanted for thinking about the right thing to do.

How the work stays coherent

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.

You can work on many projects at once. Over time, camps function more like custom agents, where small seeds of your intentions trigger hundreds or thousands of individual actions.

Each camp has its own context and workflows, so switching camps changes how your agents work.

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

Three tools, one work system

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

Useful between the big goals, too

• Jump straight to the work. cgo p api finds a matching project; cgo f takes you to festivals. Add the shell 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 with camp fresh --dry-run from that project first, including any configured branch creation or follow-up commands.

Everyday development with cgo and camp fresh

Explore the tools

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.

More video walkthroughs and demos

Fits the tools you already use

Can I keep my issue tracker?

Yes. Keep issues where your team coordinates, and use Festival for the agent's plan and work record. Intents and other work items live in files, so scripts or justfiles can connect them to an external service's API. Ask your agent to help build the connection you need. See the workflow.

Can I change agents partway through?

Yes. The next agent can read the same saved plan, decisions, and progress. Give it the festival location and access to the linked project. Agent handoff guide.

Do I need a Festival account?

The CLI tools are free to use and run locally without a Festival account. Your agent's account, model costs, and permissions remain with the provider you choose.

Keep going

• Join the Obedience Corp Discord: get help with Festival, compare workflows, and share what you build.
• Documentation: guides, use cases, and CLI reference.
• First festival tutorial: a hands-on walkthrough of the plan structure.
• Examples and templates: work you can inspect and adapt.
• Plugin authoring: extend camp and fest with your own commands.
• Report a bug or request a feature: tell us what happened or what would help.
• Give feedback or read the blog.

Festival App is in development. The CLI tools are available now. See what's coming.

If Festival is useful to you, star this repository to help other developers discover it. A bug report, a workflow you share, or an example of work you've handed off helps us improve it.

Apache License 2.0 · Built by Obedience Corp.