A local-first task board, Codex plugin, and native macOS app for managing AI-agent work across multiple projects.
Agent OS gives long-running OpenAI Codex work a durable place to record the goal, current state, next action, sources, linked Codex tasks, and completion history. It helps you move between projects without relying on chat history as the only copy of important context.
Codex tasks are excellent execution environments, but work can become difficult to coordinate when outcomes, project paths, pull requests, blockers, and follow-up are spread across many separate tasks. Agent OS adds a small continuity layer around that work:
- one durable outcome can continue across several Codex tasks;
- every task can be linked to the exact project and outcome it belongs to;
- goals, next actions, blockers, sources, and state changes remain visible;
- completed work stays reviewable instead of disappearing from an active list;
- project and task state remains on the local machine.
Agent OS does not replace Codex, GitHub, Slack, or your project repositories. It connects them without copying chat transcripts or introducing a hosted task database.
| Component | What it does |
|---|---|
| Codex plugin | Adds Task Board, project onboarding, Task Bridge hooks, MCP tools, and reusable skills. |
| macOS app | Provides Focus, Board, Done, Setup, task details, notifications, exports, and Codex handoff. |
| Agent OS runtime | Owns validated local operations and the app-facing project and outcome snapshot. |
| Private home | Stores each installation's project registry, outcomes, activity, and runtime state. |
The plugin and app share the same private home and runtime. Either component can be used first, and the Task Board remains available without the native app.
Requirements:
- OpenAI Codex desktop or CLI with plugin support;
- Ruby and Node.js;
- Apple Silicon and macOS 14 or newer for the optional native app.
Install the current plugin release:
codex plugin marketplace add andrewgolovanov/agent-os --ref v0.10.0
codex plugin add agent-os@agent-osInstall the matching native app from the same
Agent OS release.
The first component you start initializes private state in ~/.agent-os; a
source checkout is not required.
Start a fresh Codex task after installing or updating the plugin so its MCP tools, skills, and hooks are loaded. The macOS app is distributed without Apple Developer ID notarization, so follow the installation guide for checksum and Gatekeeper steps.
- Open an existing local project in Codex.
- Ask Codex to onboard it into Agent OS, or let automatic project discovery register an unambiguous local root.
- Create or select a durable outcome from the app or Agent OS MCP tools.
- Continue the linked Codex task and record material checkpoints as the result changes.
- Move verified work to Done and record any remaining external follow-up separately.
For manual onboarding, ask:
Onboard this project into Agent OS safely.
Onboarding previews changes before applying them. Projects stay in their existing folders, Git is optional, and Agent OS does not move or modify project repositories.
Agent OS stores private operational state under ~/.agent-os by default. The
project registry owns stable project identity and paths. Task Board owns durable
outcomes and their history. Task Bridge records the exact relationship between
Codex tasks and outcomes, including linked working time.
The macOS app reads this state through the selected Agent OS runtime rather than maintaining its own database. Automatic project discovery uses supported Codex metadata and does not read task bodies or import historical conversations.
Project code remains in the folders you already use. Agent OS stores paths and source identities, not copies of repositories or provider content. External writes, messages, commits, pushes, and deployments require separate explicit intent.
See Architecture and Task Board for the detailed ownership contracts.
The plugin can configure Task Bridge hooks, read-only Slack monitoring, and recurring review workflows. These integrations are opt-in and keep provider authorization separate from local Agent OS state. Installing Agent OS alone does not connect Slack or create a schedule.
See Optional integrations for setup and recovery instructions.
The optional app provides a visual workflow over the same Task Board:
- Focus for work that needs attention;
- Board for unfinished lifecycle management;
- Done for completion history, follow-up, time summaries, and PDF or Excel export;
- Setup for app, runtime, plugin, hook, and MCP health with supported repair actions.
It can open an existing linked Codex task or create a named task in the registered project with a prepared continuation prompt. Sending the prompt remains a deliberate user action.
See the macOS app README for installation, usage, and source-run instructions.
- Private task and project state stays outside the source checkout.
- Initialization does not enable provider integrations or modify repositories.
- Manual and ambiguous project changes remain preview-first.
- Plugin hooks are reviewable in Codex with
/hooks. - Release candidates can be checked for known private data with
./bin/agent-os audit-publication.
Read SECURITY.md for vulnerability reporting and security policy.
git clone https://github.com/andrewgolovanov/agent-os.git
cd agent-os
./bin/agent-os init --apply
./bin/agent-os activate --apply
./bin/agent-os doctorRun the repository validator before handing off structural changes:
./bin/agent-os validateStart with the documentation map for architecture, app, installation, integration, release, and contribution guidance. Repository rules for agents are in AGENTS.md.