Agent-OS

Agent-OS is an opinionated, filesystem-first operating system for working with AI agents. It gives people a portable way to organize projects, durable context, current execution state, reusable knowledge, and agent workflows in ordinary folders and Markdown files.

Use Claude Code, Codex, or another file-capable agent. Put the workspace in a normal local directory, Dropbox, Google Drive, or another synchronized folder. Git is useful for history and contribution, but it is not required to operate the system.

This project uses Agent-OS to mean the filesystem-first personal productivity starter in this repository. It is not affiliated with other projects that use a similar name.

Try the fictional workspace

The starter ships with a coherent fictional knowledge-work profile:

• weekly plans, commitments, and backburner items in areas/work/
• active project binders in desk/
• reusable templates and writing guidance in library/
• a decision example in memory/
• live workstream examples in state/

You can explore it before replacing anything.

The demo is a static fictional snapshot dated April 6, 2026. Its dates are intentional example data, not stale claims about your current workspace.

Start without Git

1. Download the release ZIP or copy the Agent-OS folder into your preferred local or synchronized directory.

2. Open that directory in your agent.

3. Ask:

   Read AGENTS.md and agent-os.yaml. Then summarize the demo desk and tell me the one next action for each active project or workstream.

No installer, database, daemon, account, or integration is required.

Start with Git

git clone https://github.com/aylee/agent-os.git
cd agent-os

Then open the folder in your preferred agent. Git adds version history and a contribution workflow; the files remain the operating system.

Runtime entry points

Runtime	Entry point
Claude Code	Open the folder with claude; the generated .claude/skills/ adapters use the shared filesystem contract
Codex	Open the folder with codex; project skills live under .agents/skills/
Any file-capable agent	Read AGENTS.md, then follow docs/generic-agent-guide.md

Claude and Codex are first-class adapters over the same state, not separate operating systems. Canonical policy lives in neutral files. Runtime folders contain procedures and metadata.

Make it yours

Invoke setup explicitly—/setup in Claude Code, $setup in Codex, or the procedure in docs/generic-agent-guide.md for another runtime—or personalize these files directly:

• agent-os.yaml — replace the demo instance ID, display name, profile, and local-state key
• library/reference/me.md — identity and writing voice
• areas/work/AREA.md — durable work context
• areas/work/plans.md — current focus
• desk/*/BINDER.md — projects and stable artifact links

Setup may replace fictional content only after showing what it will change. It must not overwrite user-global runtime settings or install global skills.

If you copy the starter more than once, give every copy a different instance ID and local-state key so their private machine state cannot collide.

Filesystem model

Path	Owns
AGENTS.md	Compact cross-runtime constitution and routing
agent-os.yaml	Instance identity and portable-state configuration
desk/	Project binders and project-owned artifacts
areas/	Durable responsibilities, priorities, plans, and commitments
library/	References, templates, guides, scripts, and optional config examples
state/workstreams/	Canonical resumable execution snapshots
state/receipts/	Immutable best-effort lifecycle evidence
state/handoffs/	Optional packets for real context boundaries
memory/	Curated decisions, corrections, reviews, and portable lessons
.agents/skills/	Canonical project skill sources
.claude/skills/	Generated Claude Code projections

The ownership boundaries matter:

• Binders describe the durable project and link its important artifacts.
• Workstreams own current execution truth and exactly one next action; closed workstreams use the protocol's terminal sentinel instead.
• Receipts prove transitions; they are not current state or backups.
• Handoffs are created only when work crosses an agent, runtime, machine, or context boundary.
• Memory contains curated lessons, never an automatic transcript dump.

Read docs/state-protocol.md for the exact schemas and write rules.

Progressive disclosure

Agents should not ingest the entire workspace.

1. Start with AGENTS.md and agent-os.yaml.
2. Open a binder when the user names a project.
3. Follow the binder's active-workstream link when execution state matters.
4. Load area, reference, memory, or deeper guide files only when the task requires them.

This keeps context small while leaving every important decision inspectable.

Portable state and private local state

The state/ directory is portable and human-readable. It may be copied, backed up, or synchronized with the rest of the workspace.

Credentials, raw transcripts, search indexes, caches, locks, and verbose logs must live outside the Agent-OS root. Their location is derived from state.local_state_key in agent-os.yaml:

• $XDG_STATE_HOME/agent-os// when XDG_STATE_HOME is set
• ~/.local/state/agent-os// on macOS or Linux otherwise
• %LOCALAPPDATA%\Agent-OS\\ on Windows

Portable session exports are outside the Agent-OS v1 contract. Keep raw and automatically summarized session material in external local state, then manually promote only reviewed decisions or lessons.

Dropbox and Google Drive

Agent-OS v1 supports synchronized folders with one important constraint: only one device or runtime may write a workstream at a time.

Wait for synchronization before switching writers. If a provider creates a conflicted copy, preserve every version and reconcile manually. Agent-OS never silently chooses a winner or auto-merges operating state.

See library/guides/cloud-sync.md.

Backup and restore

Synchronization is not backup. Keep periodic, versioned snapshots of the portable root outside the synchronized folder. Back up private local state separately and only with appropriate encryption and exclusions.

A valid restore must work in an empty path, including one containing spaces, and must not depend on .git or an online integration.

See library/guides/backup-and-restore.md.

Git is optional

Without Git, core behavior still works:

• open and resume projects,
• create and update workstreams,
• generate receipts and boundary handoffs,
• find recent work from receipts and artifact metadata, with modification times as a labeled fallback,
• run weekly review and closeout,
• back up and restore the workspace.

When Git is available, agents may use its history and review features. They must not treat a missing repository, branch, or commit as a state failure.

Project tree

agent-os/
├── AGENTS.md
├── CLAUDE.md
├── agent-os.yaml
├── README.md
├── .agents/skills/
├── .claude/skills/
├── areas/
├── desk/
├── docs/
├── library/
│   ├── guides/
│   ├── reference/
│   ├── scripts/
│   └── templates/
├── memory/
└── state/
    ├── workstreams/
    ├── receipts/
    └── handoffs/

First reads

• docs/agent-guide.md — detailed shared agent routing
• docs/state-protocol.md — current-state, receipt, handoff, and local-state contract
• docs/generic-agent-guide.md — operation without a native skill adapter
• docs/setup-contract.md — deterministic, preview-first personalization
• library/guides/getting-started.md — personalization and first-week workflow
• library/guides/migrating-from-work-os.md — migration from the predecessor layout

Maintainers should also read library/guides/maintainer-workflow.md.

Requirements

• A filesystem and a text editor
• A file-capable AI agent for the agent-assisted workflow
• Optional: Git for history and contribution
• Optional: Claude Code or Codex for first-class skill adapters
• Optional: Dropbox, Google Drive, or another sync provider

Verification

From the repository root:

python3 library/scripts/agent_os_doctor.py --strict
python3 library/scripts/audit_public_hygiene.py
python3 library/scripts/smoke_gitless.py

When Git is available, also run:

git diff --check

License

See LICENSE.