Skip to main content
Orkestral is a local-first desktop app where a team of AI agents works on your codebase with full context. Before you start clicking around, it helps to hold the right mental model. This page is the conceptual map of the whole product: six ideas that fit together, plus a link to the dedicated page for each one. The big picture in one sentence: you give a workspace some sources (your repos), a team of agents plans the work and turns it into issues, the local Forge executes the code changes, and everything the team learns flows into the knowledge base.

​
The mental model at a glance

Workspace

The unit of context. Everything (sources, agents, issues, knowledge) belongs to a workspace.

Sources

The repositories and folders the agents are allowed to read and change.

Agent team

A CEO orchestrator plus specialists who plan and delegate the work.

Issues and epics

Trackable work. Requests become issues, auto-grouped under epics.

The Forge

The bundled local model that executes code changes at $0 API cost.

Knowledge base

A living wiki for each workspace, built from your repos.

​
How the pieces relate

Read this flow top to bottom. Each concept feeds the next.
1

You open a workspace

A workspace is the container for one product or area. It holds your sources, your agents, your issues and your knowledge in one place.
2

You add sources

You point the workspace at the repositories and folders you want the team to work on. This is the context the agents read from.
3

The CEO agent plans

You write a request in plain language. The CEO reads the sources, identifies the stack, and decides what needs to happen. It can delegate to specialists.
4

Work becomes issues

Meaningful requests turn into issues, grouped under epics, with status, priority and assignee. The product is trackable work, not throwaway chat.
5

The Forge executes

When code changes are needed, a premium model plans the edits and the local Forge applies them deterministically on your machine.
6

Learnings flow to the knowledge base

What the team discovers about your codebase is written back into the workspace knowledge base so future work starts smarter.
Everything runs on your machine. Your code, conversations, agents and data stay local under ~/.orkestral. No server is required and there is no telemetry.

​
Workspace: the unit of context

A workspace is the boundary for everything Orkestral does. When you switch workspaces, you switch the whole world: a different set of sources, a different agent team, different issues and a different knowledge base. Nothing leaks across workspaces. Use one workspace per product, client or major area. Each workspace also carries its own accent color so you can tell them apart at a glance.

Learn about workspaces

How to create, switch and organize workspaces, and what lives inside each one.

​
Sources: the repos and folders

Sources are the repositories and local folders you connect to a workspace. They are the ground truth the agents read from: file contents, git status, diffs and history. Without sources, the team has no context to plan against. You decide which sources a workspace can see. The agents read across them when they plan, and the Forge writes changes back into them when it executes.

Learn about sources

How to add repositories and folders, and how the agents use them as context.

​
The agent team: CEO plus specialists

Orkestral does not give you one chatbot. It gives you a team with a reporting hierarchy.
  • The CEO (orchestrator) reports to you. It reads the repo, plans and delegates.
  • The Tech Lead and Code Reviewer report to the CEO.
  • Specialists (Frontend, Backend, DevOps, QA, Designer) report to the Tech Lead.
You talk to the CEO in natural language. To route a request straight to a specialist, mention @agent in chat. The CEO can also propose and hire an initial team for a new workspace.
Premium models do the planning, the local Forge does the executing, and you stay in control. That split is the heart of how Orkestral keeps cost low without losing quality.

Learn about the agent team

The roles, the hierarchy, hiring a team, and routing work with @agent.

​
Issues and epics: trackable work

Every meaningful request becomes an issue. Issues carry status, priority, assignee and parent/child links, and they are auto-grouped under epics. Server-side dedup keeps you from collecting duplicates. This is the part that makes Orkestral an operational deck rather than a chat window: work does not disappear into a scroll buffer. A conversation can spawn an issue, an issue can run an agent, and the result is tracked.
An issue is a single unit of work. An epic groups related issues so a larger goal stays organized. Orkestral groups issues under epics automatically.
Mostly from chat. When you describe work to the CEO, it turns the request into one or more issues with the right metadata.
Yes. Issues and chat share the same workspace context, so an issue can run an agent to plan or execute the work.

Learn about issues and epics

Statuses, priorities, assignees, epics and how requests become trackable work.

​
The Forge: local execution at $0 API cost

The Forge is a bundled local code model (Qwen2.5-Coder, running fully offline) that executes code changes on your machine. The pipeline is built to keep API cost near zero without writing wrong code.
1

A premium model plans the change

It decides what files to touch and what edits to make.
2

The Forge emits the edits

Running locally, it produces SEARCH/REPLACE edit blocks for the change.
3

A deterministic applier writes them

Edits are applied by exact match, then whitespace-normalized, then a safe single-match fuzzy pass. Anything ambiguous is rejected rather than applied wrong.
4

Escalate only if needed

If the edits cannot be applied cleanly, Orkestral escalates to a premium model once as a fallback. Otherwise the run finishes at $0 API cost.
The applier never guesses. If an edit is ambiguous, it refuses to write rather than risk corrupting your file. A cost dashboard shows how many runs were resolved locally versus escalated.

Learn about the Forge

How local execution works, when it escalates, and how to read the cost dashboard.

​
Knowledge base: the workspace brain

Each workspace has a wiki-style knowledge base: pages with wikilinks and a graph view. It is auto-generated from your repos and searched with a mix of lexical (BM25) ranking and local semantic search (on-device embeddings). No cloud is involved. The knowledge base closes the loop. Agents read from it when they plan, and learnings get written back to it, so each task makes the next one better informed.

Learn about the knowledge base

Pages, wikilinks, the graph view, and how local search retrieves context.

​
How it all stays unified

Chat, issues, git status and diffs, code reviews and the knowledge base all live in the same workspace and feed each other. The agents read across all of them. That is why a single conversation can plan work, file issues, run the Forge, review the result and write what it learned back to the brain, without you stitching tools together.

​
What to do next

Set up your first workspace

Create a workspace and make it the home for your project.

Connect your sources

Add the repos and folders the agents will work on.

Meet the agent team

Hire a team and learn how to route work with @agent.

See the Forge in action

Watch local execution apply real code changes at $0 cost.