Festival: A vibe engineering framework

Vibe coding is a fast way to explore an idea, build a demo, or recreate something familiar. When you go beyond the demo, build something new, or work where a mistake could cost millions, you need more control over how the work gets done.

Vibe engineering means turning AI-assisted work into a process you can inspect, improve, and delegate repeatedly. You define the outcome, review important decisions, and check the evidence behind the result. The aim is to let agents carry more of the work without having to babysit every step.

Festival gives you the tools to build that process through templates and configuration: Fest for long-term goals and automated planning, Camp for shared context across sessions, and Obey for oversight and background orchestration. You shape how agents work, see where they need attention, and refine the process for the next run. Plans, decisions, progress, and checks stay in files and Git, so you can inspect the work and continue in another session.

Try it on one real goal · See a completed build · How it works · 简体中文

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

Start with one goal in a repository you already use. Keep your existing coding agent, let it help set up Camp and Fest, and review the result. Add Obey when you want the daemon to manage execution.

Set up with your agent · Configure Obey

How the components fit together

flowchart TB
    accTitle: How Festival components work together
    accDescr: Fest supplies plans and tracks progress. Camp shares saved context across sessions. Obey launches and supervises agents through a background daemon. All three work with your agent sessions.
    subgraph festival["Festival: templates + configuration"]
        fest["Fest<br/>Long-term goals<br/>Automated planning"]
        camp["Camp<br/>Shared context<br/>Across agent sessions"]
        obey["Obey<br/>Overseer<br/>Background daemon"]
    end

    agents["Agent sessions<br/>Your providers and models"]

    fest <-->|Tasks and progress| agents
    camp <-->|Read and record context| agents
    obey -->|Launch and supervise| agents

A camp is the workspace around your goals. A festival is a larger goal inside it. Each camp can have its own projects, knowledge, templates, and working practices. Switch camps with camp switch (csw); a new agent session can read the saved plans and decisions before continuing the work.

You can use Camp and Fest directly with an agent that reads files and runs commands, including Claude Code, Codex, Grok Build, Cursor, or OpenCode. Add Obey when you want daemon-managed execution; its provider setup guide covers the providers it can launch and supervise.

The festival command installs and updates the tools. The base suite includes camp, fest, and the festival manager. Install Obey separately with festival install obey, which adds both obey and ob.

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

Try it on one real goal. Start with one repository and one goal you already want to finish. Use your existing coding agent to plan the work, execute it, and leave the results ready for review.

1. Set up with your agent

Replace the brackets and paste this into your coding agent. It will install Festival if needed, create one camp, and link your existing repository. Git is required.

Help me set up Festival for this goal: [what you want done and how you'll know it worked].
My existing repository is at: [full local path].

If `camp`, `fest`, or `festival` is missing, install Festival. 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`. On Windows x64, install Scoop, then run `scoop install git`, `scoop bucket add obedience https://github.com/Obedience-Corp/scoop-bucket`, and `scoop install obedience/festival` in PowerShell. After installing, run `festival doctor` to check the install.

Use the installer that owns the suite for updates. For Scoop, run `scoop update festival`. For a Festival-managed install, run `festival update` without `--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>"`. Read `camp create --help` before adding flags. Use `camp create` for this. Do not run `camp init` or `festival setup`. Use the camp path printed by the command (by default, `~/campaigns/<name>`).

Set up navigation for my shell, adding the following lines to its config only if they are missing. For zsh or bash, use `eval "$(camp shell-init <shell>)"` and `eval "$(fest shell-init <shell>)"`, replacing `<shell>` with `zsh` or `bash`. For fish, use `camp shell-init fish | source` and `fest shell-init fish | source`. For PowerShell 5.1 or 7, add `Invoke-Expression (& camp shell-init powershell | Out-String)` and `Invoke-Expression (& fest shell-init powershell | Out-String)` to `$PROFILE`. Tell me to open a new terminal and run `csw <name>`; you can keep working from the camp root.

From the camp root, run `camp project link <full-local-repo-path> --yes`. This leaves the repository in place, links it under `projects/`, and adds a `.camp` attachment file to it.

Read the camp and project instructions, then use `fest understand` to learn the workflow. Skills are optional. Create a festival for my goal, link it to the project with `fest link` from the festival directory, and run the `fest next` loop. Ask me when you need a decision. Show me the festival path so I can follow progress, and leave the results and verification evidence ready for review.

The agent setup guides cover optional skills and integrations for your tool.

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

npm install -g @obedience-corp/festival

scoop install git
scoop bucket add obedience https://github.com/Obedience-Corp/scoop-bucket
scoop install obedience/festival

festival doctor
camp create my-camp

cd ~/campaigns/my-camp
camp project link /path/to/your-existing-repo

Enable the shell integration. The shell shortcuts (csw, cgo, fgo, fls, and cr) are shell functions, so they exist only in a shell that has loaded the integration. The setup prompt asks your agent to add it, but an agent cannot load it into a terminal you already have open. Check your shell config and add these lines if they are missing.

For zsh, add to ~/.zshrc (for bash, replace zsh with bash and use ~/.bashrc):

eval "$(camp shell-init zsh)"
eval "$(fest shell-init zsh)"

For fish, add to ~/.config/fish/config.fish:

camp shell-init fish | source
fest shell-init fish | source

Open a new terminal and run type csw. It should report a shell function. If it reports "not found", the lines are not in the config file your shell reads at startup. Homebrew, npm, and Linux package installs also ship a sourceable helper file that adds tab completion; the shell setup guide lists the path for each install method.

2. Give your agent a goal

If you used the setup prompt, your agent already has your first goal. For manual setup or your next goal, tell it:

I want [what you want done]. Success means [what you will check]. Create a festival for it, link it to the project, and run the fest next loop. Show me the festival path and leave the results ready for review.

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

3. 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 at the festival path your agent gives you and run fest watch.

When the work is ready, ask your agent to show you:

• The result against your original goal and success criteria.
• The changed files and commits in your project.
• The test and review evidence, including failures, unresolved questions, and decisions that still need you.

Use the saved festival plan and work records together with your project's Git history to review what happened before accepting the result.

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.

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

Add background orchestration with Obey

After installing the Festival suite, add Obey:

festival install obey
obey ping
ob providers

Follow the Obey setup guide to check its service and configure a provider and model. From a planned festival, preview the execution context before starting the task loop:

ob fest execute --dry-run
ob fest execute

Obey oversees the session while the agent works through the festival. Use obey top from the camp to follow sessions. For individual developer tasks, ob can plan from a spec, review a diff, or generate a commit message.

Obey's binaries are publicly available even though its source repository is private. Configuration · Everyday use · Troubleshooting

The festival manager also installs CLI plugins. Run festival browse to explore them, or read suite and plugin management.

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.

camp create work
csw work
csw my-camp

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.