Agent workflows
Agents move an initiative, bug, or todo from planned work into an execution tool while keeping the result tied to that work. They work best when the source item is already a useful spec.
Send to app opens one item in a tool now. Local agents run on your machine for you. Cloud agents stay online, do not depend on a person's computer, and can be shared by a team.
Choose your path
Choose the path by who should be able to use the agent and where it runs.
| Audience | Path | Best for |
|---|---|---|
| Beginner | Send to app | You want to open one work item in Codex, Cursor, Claude Code, Windsurf, OpenCode, or Terminal with context already included. |
| Intermediate | Local Workers | You want Codex to pick up queued work from your machine through Desktop or the CLI. |
| Advanced | Build a Local Agent | You want to build an agent that runs on your machine, for your queued work. |
| Advanced | Build a Cloud Agent | You want an agent that stays online, can be shared by a team, and wakes from webhooks. |
Core model
The same execution model applies to local workers, cloud workers, and agent endpoints.
| Concept | What it means |
|---|---|
| Agent | The capability users can send work to, such as Codex local or a custom agent app. |
| Worker | The runtime that can execute sessions for an agent. Local workers run on one user's machine. Cloud workers run as a service that stays online. |
| Session | One visible unit of queued agent work, usually tied to an initiative, bug, or todo. Creating a session queues work. |
| Claim | The lease that lets one worker run one session. Work starts only after the claim succeeds. |
| Activity | A progress, plan, URL, completion, failure, release, cancellation, or policy event emitted by the worker. |
How agent work flows
- A person sends work through Send to app, the CLI, or a custom integration.
- The platform creates or launches the right execution path and keeps the source work attached.
- For queued work, it creates an Agent Session.
- A local or cloud worker polls for eligible sessions, claims one session, and executes it.
- The worker reports progress, plans, external URLs, completion, failure, or blockers.
- The original initiative, bug, or todo remains the review surface for status, comments, recaps, taxonomy, and analytics.
Execution modes
Send to app is for one item at a time. It builds a prompt from the initiative, bug, or todo and opens a configured coding tool or terminal flow. Use it when a person wants to stay in control of the next step.
Local agents run on your machine and belong to the signed-in owner. Only you can delegate work to them. They can use local tools, repositories, and secrets that you explicitly make available through your workflow. They require an OAuth app, a user OAuth session, local worker configuration, and polling.
Cloud agents stay online as shared services. Team members can send work to them when they have access, and the agent keeps running without depending on anyone's laptop. They require an OAuth app, a cloud worker configuration, and a webhook for notifications. The webhook wakes up the service; the worker still needs to fetch, claim, update, and complete sessions through agent endpoints.
Trust boundary
Initiatives, bugs, todos, comments, documents, and prompts are execution context. They are not runtime policy.
Trusted instructions come from platform policy, the agent profile, the worker configuration, and the local workflow file. Workers must enforce policy before filesystem access, shell execution, network access, workspace writes, or external side effects.
Use Send to app for the first launch path, Use in Terminal for CLI handoff, Local Workers for built-in Codex workers, Build a Local Agent for private local execution, and Build a Cloud Agent for shared cloud execution.