Festival

AI can generate the pieces.
Festival keeps the work coherent.

Hand off a goal, approve the plan, and focus on other work while your agent runs. Come back to results you can trace through the plan, decisions, checks, and commits that produced them.

Festival is an operating environment for long-running agent work. It keeps the context and progress in files and Git, so the work can continue across sessions, agents, and months or years of development.

Use it with Claude Code, Codex, Grok Build, Cursor, OpenCode, or another agent that can read files and run commands. Your agent calls fest next for its next step, does the work, and records the result.

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

Four days of agent work, alongside everything else

In the camp-hardening festival, agents worked on safeguards against data loss in the Camp CLI over four days while the operator did other work in parallel. The saved plan and progress let the next agent continue the same work after a tool change. The resulting safeguards for project removal and worktree cleanup were reviewed and merged.

Drafted by Fathom. Execution started with Grok, finished with Codex.

This is a replay of the festival's recorded progress, not a CLI recording. Read the actual plan and work record.

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.

Run this from the directory where you keep your work, then answer the prompts for the camp's description and mission:

camp init my-camp
cd my-camp

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.

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

Watch a camp take shape. This recording uses camp project add --local; the instructions above link an existing repository without moving it.

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.

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.

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

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.

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.
• 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

Open a section to see the commands in use. The recordings stay on this page, at a readable size.

Move between projects, plans, and camps

cgo jumps to a project or planning directory; csw switches camps.

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.

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.

Watch a longer Festival session

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

• 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.