Synchestra — as in synchronized orchestra — is a modular, opinionated platform for orchestrating multi-platform AI agents asynchronously. It manages the I/O of AI-driven development: the inputs (prompts, specifications, task queues) and the outputs (code, documents, artifacts) — keeping token usage minimal, output velocity high, and humans in the loop.

AI agents are getting powerful. Running a single agent on a single task works. But real work isn't a single task — it's a tree of tasks, features, sub-features, dependencies, and decisions that unfold over time.

The moment you try to coordinate multiple agents — or even one agent across multiple sessions — you hit the same problems:

• Context is expensive. Every time an agent starts, it needs to understand what's going on. Loading the full project context burns tokens and loses focus. Most of that context is irrelevant to the current task.
• State is scattered. What's been done? What's left? What's blocked? The answers live in chat logs, git history, your head, and nowhere canonical.
• Agents can't find each other's work. Agent A finishes a sub-task. Agent B needs the output. Without a shared protocol, you're the glue — copying context between sessions, platforms, and tools.
• Humans can't see what's happening. When agents work asynchronously across platforms (Claude Code, Cursor, GPT, custom scripts), there's no dashboard, no progress bar, no single place to look and understand: where are we?

Existing tools solve the agent runtime problem well — how to call tools, chain reasoning, manage prompts. They haven't solved the coordination problem: how do agents share state, minimize redundant work, and keep humans in the loop?

Synchestra is that coordination layer.

Synchestra is a mental framework, a set of tools, and a runtime that turns a git repository into a coordination protocol for AI agents.

At its core, Synchestra is a chain of small, automatable steps and background checks that anyone could do manually — but nobody has time to do consistently. Think of it as a disciplined workflow engine tuned to one mission: envisioning, planning, and managing the development of software projects with AI agents.

• CLI and MCP server. Agents call Synchestra to create, search, validate, and update project state. Humans use the same CLI for manual operations. See CLI spec.
• Skills. Pre-built, agent-ready instructions that wrap CLI commands with trigger conditions, parameters, and error handling. Any agent platform can use them — with or without the full Synchestra runtime.
• Daemon. Runs as a background process that spawns agents when new tasks are queued, manages headless agent sessions in highly focused mode, and runs pre/post micro-task chains around each prompt.
• Web UI and HTTP API. Remote access to everything — edit projects, queue tasks from your phone, monitor progress. Users authenticate via GitHub OAuth or Firebase; their identity is used to sign prompt commits and co-author output artifact commits.
• Git hooks and CI guards. Pre-commit, pre-push, and GitHub Actions workflows validate the structure and consistency of Synchestra project files on every change.

• Hierarchical and nested. Features have sub-features. Tasks have sub-tasks. The directory tree mirrors the work breakdown structure. This isn't a flat backlog — it's a tree that reflects how work actually decomposes.
• Modular but opinionated. Modules are flexible and composable, but they communicate through enforced naming conventions at the top level (e.g., tasks live in tasks/) with configurable details (e.g., max nesting depth, source code location). A README.md in every directory. A predictable structure that agents can navigate without custom tooling.
• Multi-platform. Agents running in Claude Code, Cursor, Windsurf, GPT, or a custom script can all participate. The shared state is the repo, not a proprietary runtime.
• Token-efficient by design. Not just structurally — Synchestra actively minimizes token usage through automatic context generation, model selection, and micro-task decomposition (see How Token Efficiency Works).
• Async-first. Agents work independently and asynchronously. Coordination happens through the repo state, not real-time messaging.

A Synchestra-managed repository follows this structure:

repo/
  README.md                          # Repository overview

  spec/                              # Product specifications (configurable per project)
    features/
      feature-1/
        README.md                    # Feature description, acceptance criteria
        sub-feature-1/
          README.md
        sub-feature-2/
          README.md

  docs/                              # Product documentation (configurable per project)
    ...

  synchestra/                        # Orchestration layer (hardcoded name)
    projects/
      my-project/
        synchestra-project.yaml      # Project configuration
        tasks/                       # Task queue
          task-1/
            README.md                # Task description, status, assignment
            subtask-1/
              README.md
            subtask-2/
              README.md
          task-2/
            README.md

spec/ and docs/ live at the repository root — they are the product's specification and documentation. synchestra/ is the orchestration layer that manages projects, each with its own task tree. The locations of spec/ and docs/ are configurable per project via synchestra-project.yaml.

Every directory has a README.md. This is the atomic unit of Synchestra. Each README contains the context an agent needs to understand that node: what it is, what's expected, what's done, what's blocked — and what questions remain open.

The directory tree is the work breakdown structure. Nesting means decomposition. A feature directory contains its sub-features. A task directory contains its sub-tasks. The hierarchy is both organizational and navigational.

Naming conventions are the API. Agents looking for work check synchestra/projects/{project}/tasks/. Agents needing requirements check spec/features/. No registration, no discovery protocol — just filesystem semantics enforced by schema validation.

Everything is human-readable text. State is stored as YAML, JSON, or Markdown. Task status lives in the task's parent document alongside a list of sub-tasks and their statuses. Agents read and update state through the Synchestra CLI, which validates changes against the project schema.

Synchestra uses inGitDB as its storage engine. inGitDB treats the git repository as a structured database with schema validation, enforcing the hierarchical data model that Synchestra depends on.

This means:

• No external database. The repo is the database. Git history is the audit trail.
• Schema-enforced structure. The inGitDB schema validates directory layout, required fields, naming conventions, and relationships between documents.
• Consistency guardrails at every layer. Both the inGitDB CLI and Synchestra CLI run on git pre-commit and pre-push hooks, and inside GitHub Actions workflows. Invalid changes are rejected before they reach the repository.

Token efficiency isn't just about loading fewer files. Synchestra optimizes at multiple levels:

Minimal context generation. For each micro-task, Synchestra automatically generates the minimum context an agent needs — the task description, the parent chain for broader context, sibling tasks for awareness of parallel work, and outstanding questions from prior attempts. Everything else stays unloaded.

Smart model selection. Not every task needs the most powerful (and expensive) model. Synchestra can select the minimal viable model for each task — either by configuration rules or by using a smaller model to assess task complexity before routing to the right tier.

Micro-task chains. Because Synchestra knows the workflow structure, it can run configured chains of specialized micro-tasks before and after processing a user's prompt. Some run sequentially (e.g., validation before submission), others in the background (e.g., updating cross-reference links, running consistency checks).

Persistent outstanding questions. Every document maintains an "Outstanding questions" section. When a task is restarted or a new agent picks up related work, it inherits awareness of known pitfalls and pending decisions — avoiding wasted tokens rediscovering known issues. Questions can be linked to sub-tasks; when the sub-task completes, a specialized sub-agent can automatically resolve and remove the question.

Multiple agents working on the same project will inevitably compete for tasks and touch shared files. Synchestra handles this with a layered approach:

Synchestra's philosophy is commit often. When an agent starts work, it must:

1. Claim an unclaimed task by updating its status to "claimed/wip"
2. Commit and push immediately

If the push fails due to a merge conflict, another agent already claimed the task. The agent moves on to the next available task or exits. This is standard distributed locking — implemented through git, requiring zero additional infrastructure. The synchestra-claim-task skill handles this entire flow for agents automatically.

When conflicts do occur (e.g., two agents working on different tasks update the same document section), Synchestra launches a specialized AI sub-agent that:

1. Analyzes the merge conflict
2. Merges changes automatically if possible
3. Flags the issue and queues it for rework or human resolution if not

Synchestra ships with a library of skills — focused, self-contained instructions that teach AI agents how to perform specific Synchestra operations. Each skill wraps a single CLI command and tells the agent exactly when to use it, what parameters to pass, and how to handle every exit code.

Skills work with any orchestrator. While skills are designed for the integrated Synchestra workflow, they don't require it. Any agent platform that supports custom instructions — Claude Code, Cursor, Windsurf, GPT, custom scripts — can load Synchestra skills and use them independently. An agent doesn't need the Synchestra daemon, web UI, or even a Synchestra-managed project to benefit from skills. If the agent has access to the CLI, it can use the skills.

This makes skills the lowest-friction entry point to Synchestra: add a few skills to your agent's configuration and it gains structured task management, even if the rest of your workflow is entirely custom.

See the agent-skills feature spec for design principles — one skill per action, consistent exit codes, and why skills wrap the CLI rather than replacing it.

Synchestra adapts to how your project is organized:

• Single repo. Synchestra lives alongside your code in the same repository. Simple and self-contained.
• Multi-repo projects. If your project spans multiple repositories (frontend, backend, infrastructure), create a dedicated Synchestra repository for the orchestration layer. This repo holds the specs, tasks, and project state, and can create and update files in your project repositories. The branching strategy and cross-repo synchronization are defined in a dedicated specification file.
• Multiple projects. For developers or teams working across multiple projects in parallel, a dedicated Synchestra org provides a single control plane across all of them.

These are runtimes — they execute agents, manage prompts, and chain tool calls. Synchestra doesn't replace them. It sits beneath them as the shared state and coordination layer. Your CrewAI agents and your Claude Code session can coordinate through the same repo. Load Synchestra skills into any of these frameworks and agents gain structured task claiming, status reporting, and conflict-safe coordination without changing their runtime.

These track work for humans. Synchestra tracks work for agents and humans. The directory structure is both machine-navigable and human-readable. An agent doesn't need an API client to check task status — but it gets validation and consistency guarantees when it uses one.

CI/CD pipelines are linear and event-driven. Synchestra workflows are hierarchical and async. A task can spawn sub-tasks dynamically. Progress is visible at every level of the tree.

"Isn't this just a well-organized repo?"

You can absolutely do what Synchestra does manually. You could also deploy software without CI/CD, manage infrastructure without Terraform, and track bugs without an issue tracker. Synchestra is the automation and discipline layer that makes the "well-organized repo" approach sustainable. It's the chain of small steps and background checks that anyone could do but nobody has time to do consistently — schema validation, context generation, model selection, conflict resolution, cross-reference updates, progress tracking. The value isn't in any single convention. It's in the system that enforces and automates all of them together.

"Naming conventions are fragile. What happens when they break?"

They don't break silently. Synchestra enforces conventions at multiple checkpoints: the CLI validates on every operation, pre-commit hooks catch problems before they enter the repo, pre-push hooks catch anything that slipped through, and GitHub Actions provide a final safety net. The high-level structure is enforced (tasks go in tasks/), while the details are configurable (max nesting depth, source code paths, custom modules). inGitDB's schema validation ensures that the structural invariants hold at every commit.

"How does async coordination work without conflicts?"

Through the same mechanism distributed systems have used for decades: optimistic locking. Agents claim tasks by committing a status change and pushing. If the push fails, someone else got there first. For the remaining edge cases — two agents editing different parts of the same file — Synchestra provides AI-powered merge resolution that either handles it automatically or escalates to a human. The "commit often" philosophy minimizes the window for conflicts in the first place.

"Does this actually scale beyond a solo developer?"

Synchestra started small — one developer, a few projects, a $10/month VM. But the architecture scales naturally: git already handles distributed collaboration, inGitDB's schema validation works regardless of team size, and the claim-and-push protocol handles concurrency without a central coordinator. The same conventions that keep a solo developer organized keep a team aligned.

Core features driving Synchestra's development:

See feature specifications for detailed specs and dependency graph.

Try it instantly:

• Fork a demo project or use a Synchestra template repository to explore the structure and conventions locally.
• Sign in at synchestra.io with GitHub OAuth, choose the repo(s) you want to orchestrate, answer a few setup questions, and you're running.

For full control: Install Synchestra on your own VM for persistent daemon mode, headless agent management, and full CLI access. For evaluation, Synchestra can provide a demo VM, or you can run it entirely within a GitHub Actions workflow.

Synchestra's own development is managed by Synchestra. We build the tool with the tool — which means every rough edge gets felt immediately and fixed quickly.

Synchestra-managed projects:

• synchestra-project — Synchestra's own development project (specs, tasks, project state)
• synchestra-go — CLI, daemon, server, HTTP API, and task runner (Go)
• synchestra-app — Web UI frontend (TypeScript, Angular, Ionic)

Synchestra is in active development. The conventions, module structure, and CLI are being built and refined through daily use on real projects.

• What is the full lifecycle of a cross-repo task — from branch reservation through integration testing to merge? (Early vision exists; dedicated specification pending. See Cross-Repo Sync.)
• What is the configuration format for micro-task chains? (Conceptual stage; GitHub Actions-inspired YAML being explored. See Micro-Tasks.)
• How does Synchestra interact with agent platform settings when it's not the direct model caller? (Configurable: Synchestra can decide, or the user can override via UI/CLI/API. Hints or arguments are passed to the underlying platform.)

• spec/
  • features/: 3 outstanding questions
    • micro-tasks: 4 outstanding questions
    • cross-repo-sync: 4 outstanding questions
    • model-selection: 4 outstanding questions
    • conflict-resolution: 3 outstanding questions
    • outstanding-questions: 3 outstanding questions
    • claim-and-push: 3 outstanding questions
    • agent-skills: 3 outstanding questions
    • cli: 3 outstanding questions
  • project-definition/: 2 outstanding questions

Apache License 2.0. See LICENSE for details.

• Vision
• Roadmap
• Features
• Skills
• CLI Spec
• Self-Hosting
• inGitDB