All of Orkestra’s configuration, agent templates, and runtime state for a repository live in a single directory: .orkestra/. The first time you run any ork command in a repository, that directory is created automatically and Orkestra treats the repository as a project.
One repository equals one project. There is no multi-repo setup.
What’s in an Orkestra project
The .orkestra/ directory has two layers: files you commit, and runtime data Orkestra generates.
Committed files — checked into version control and shared across your team:
| Path | Purpose |
|---|---|
.orkestra/workflow.yaml | Defines all flows and their stages |
.orkestra/agents/ | Prompt template files, one per stage |
.orkestra/scripts/ | Shell scripts for gates and worktree lifecycle |
Runtime data — generated by Orkestra, gitignored:
| Path | Purpose |
|---|---|
.orkestra/.database/ | SQLite database storing all Trak state |
.orkestra/.logs/ | Agent output logs |
.orkestra/.worktrees/ | Per-Trak git worktrees |
.orkestra/.artifacts/ | Stage artifacts from active and completed Traks |
Team collaboration
Because workflow.yaml, agents/, and scripts/ are committed, your entire team shares the same pipeline definition. When you update a prompt template or add a stage to the workflow, every subsequent Trak picks up the change.
The runtime directories are gitignored, so each developer or CI machine maintains its own local Orkestra state independently.
Lifecycle scripts
Two scripts in .orkestra/scripts/ run at the edges of a Trak’s worktree lifecycle:
worktree_setup.sh— runs when a new worktree is created for a Trak. Use it to copy.envfiles, install dependencies, or set up anything the agent needs in an isolated worktree.worktree_cleanup.sh— runs before a worktree is removed. Use it to tear down anythingworktree_setup.shcreated. Failures are silently ignored — cleanup always proceeds.
Both scripts receive the worktree’s absolute path as their first argument ($1).
What’s next
See Traks to understand how work is created and tracked in a project.