# OpenFlow overview

OpenFlow is a desktop workspace for agents. Use a direct chat for one task in a conversation; build a workflow when several agents should pass results to one another.

For example, connect a planner to a checklist agent. The planner turns your request into a plan; the checklist agent waits for it, then turns it into actionable items. You can inspect both conversations and reuse the workflow with a different request.

## Start using OpenFlow

1. [Install OpenFlow](https://philbotar.github.io/OpenFlow/getting-started/). The packaged macOS app needs no development toolchain.
2. [Connect a provider](https://philbotar.github.io/OpenFlow/guides/provider-setup.html): hosted credentials, ChatGPT sign-in, AWS credentials, or a local model server.
3. [Start a direct chat](https://philbotar.github.io/OpenFlow/guides/direct-chats.html), or [build your first workflow](https://philbotar.github.io/OpenFlow/guides/first-workflow.html) from two prompts you paste into the editor.

[How OpenFlow works](https://philbotar.github.io/OpenFlow/concepts/how-openflow-works.html) explains dependencies, handoffs, and your role during a run. [Using the app](https://philbotar.github.io/OpenFlow/guides/using-the-app.html) locates the controls. [For new users](https://philbotar.github.io/OpenFlow/guides/for-new-users.html) keeps old links working.

## Work with the app

| Task | Guide |
| --- | --- |
| Chat with one agent | [Direct chats](https://philbotar.github.io/OpenFlow/guides/direct-chats.html) |
| Create, configure, and validate a graph | [Workflow authoring](https://philbotar.github.io/OpenFlow/guides/workflow-authoring.html) |
| Answer, approve, retry, replay, or resume | [Runs and recovery](https://philbotar.github.io/OpenFlow/guides/runs.html) |
| Work in a repository and manage saved files | [Projects and persistence](https://philbotar.github.io/OpenFlow/guides/projects-and-persistence.html) |
| Configure tool approval, skills, subagents, search, or MCP | [Tools and integrations](https://philbotar.github.io/OpenFlow/guides/tools-and-integrations.html) |
| Run a saved workflow at a time or interval | [Scheduling workflows](https://philbotar.github.io/OpenFlow/guides/scheduling.html) |
| Recover from a setup or run failure | [Troubleshooting](https://philbotar.github.io/OpenFlow/troubleshooting/) |

## Look up behavior

| Question | Reference |
| --- | --- |
| How do workflows and runs relate? | [Concepts](https://philbotar.github.io/OpenFlow/concepts/) |
| What does a workflow, node, edge, or run mean? | [Workflows and runs](https://philbotar.github.io/OpenFlow/concepts/workflows-and-runs.html) |
| What does a code term mean? | [Glossary](https://philbotar.github.io/OpenFlow/glossary.html) |
| What are the settings, defaults, and limits? | [Configuration reference](https://philbotar.github.io/OpenFlow/reference/configuration.html) |
| Which endpoints, credentials, and defaults does each provider use? | [Provider profiles](https://philbotar.github.io/OpenFlow/reference/providers.html) |
| Which tools can an agent call? | [Tools reference](https://philbotar.github.io/OpenFlow/reference/tools.html) |
| Where does OpenFlow store files and credentials? | [Data locations](https://philbotar.github.io/OpenFlow/reference/) |
| What leaves the app, and what requires trust? | [Security and data](https://philbotar.github.io/OpenFlow/security-and-data.html) |

## Develop OpenFlow

[Build from source](https://philbotar.github.io/OpenFlow/getting-started/build-from-source.html) sets up a development checkout. [Contributing](https://philbotar.github.io/OpenFlow/contributing/) describes the change and review workflow; [Architecture](https://philbotar.github.io/OpenFlow/architecture/) maps the implementation.

### Contribute

| Page | Covers |
| --- | --- |
| [Development commands](https://philbotar.github.io/OpenFlow/contributing/commands.html) | Build, check, and test commands |
| [Testing workflows](https://philbotar.github.io/OpenFlow/contributing/testing-workflows.html) | Which checks a change needs |
| [Development lanes](https://philbotar.github.io/OpenFlow/contributing/development-lanes.html) | Classifying a change |
| [Coding patterns](https://philbotar.github.io/OpenFlow/contributing/coding-patterns.html) | Ownership, errors, persistence, test placement |
| [Build and test troubleshooting](https://philbotar.github.io/OpenFlow/contributing/build-troubleshooting.html) | Source-checkout failures |
| [Releasing OpenFlow (macOS)](https://philbotar.github.io/OpenFlow/contributing/releasing.html) | Tagging and publishing a release |
| [Documentation website](https://philbotar.github.io/OpenFlow/contributing/documentation-site.html) | The site and Markdown exports |
| [README workflow demo GIF](https://philbotar.github.io/OpenFlow/contributing/readme-demo-gif.html) | Recording the README demo |

### Architecture pages

| Page | Covers |
| --- | --- |
| [Architecture contract](https://philbotar.github.io/OpenFlow/architecture/contract.html) | Layer boundaries and dependencies |
| [Run lifecycle](https://philbotar.github.io/OpenFlow/architecture/end-to-end-runtime.html) | UI → desktop → orchestration → engine → provider |
| [Agent execution and context](https://philbotar.github.io/OpenFlow/architecture/technical-overview.html) | Node scheduling and context |
| [Orchestration crate layout](https://philbotar.github.io/OpenFlow/architecture/orchestration-layout.html) | Module map |
| [Provider adapters](https://philbotar.github.io/OpenFlow/architecture/provider-adapters.html) | Model transport and routing |
| [Run persistence](https://philbotar.github.io/OpenFlow/architecture/run-persistence.html) | Checkpoints, resume, replay |
| [Threading and concurrency](https://philbotar.github.io/OpenFlow/architecture/threading-concurrency.html) | Async runtimes |
| [Callable agents in orchestration](https://philbotar.github.io/OpenFlow/architecture/callable-agents.html) | Saved-agent snapshots |
| [Overseer output repair](https://philbotar.github.io/OpenFlow/architecture/output-repair.html) | Repairing malformed node output |
| [Plan → Execute internals](https://philbotar.github.io/OpenFlow/architecture/plan-execute.html) | The planning gate |
| [Architecture diagrams](https://philbotar.github.io/OpenFlow/architecture/diagrams/) | Layer diagrams |

The [repository map](https://philbotar.github.io/OpenFlow/FOLDER_STRUCTURE.html) locates source packages. Historical plans and roadmap entries do not establish current product behavior.