A portable Git-backed context and workflow layer for agents like Claude Code, Codex, Hermes, OpenClaw, Cursor, and Devin. Evolves alongside you and your agents.
Chat history, project instructions, and copied prompts drift apart. Context OS puts the durable parts in plain Markdown: who you are, what you are working on, decisions already made, and the workflows you want an agent to follow.
Claude Code, Codex, Hermes, and OpenClaw, plus the experimental Cursor and Devin adapters, read the same repository state. A deterministic lifecycle kernel turns reviewed setup, checkpoint, and close requests into hash-checked proposals and receipts, without treating native memory as the source of truth.
| What you need | How Context OS handles it |
|---|---|
| Bring useful context forward | A source-neutral migration workflow turns selected chats, project instructions, memory exports, and documents into reviewable files. |
| Work across coding agents | Provider-neutral state, skills, and lifecycle transitions live outside host adapters. Registered runtimes share the same kernel. |
| Add the tools that fit | A generated integration catalog documents install scope, data access, side effects, and confirmation gates. Nothing is enabled automatically. |
| Keep context useful | Session handoffs, staleness checks, decision logs, and reviewable memory proposals make maintenance part of the normal workflow. |
Context OS does not scrape every account, sync product UIs automatically, or install integrations on setup. Imports are selective, browser-project sync is manual, and external capabilities remain opt-in.
Personal and business context often belongs in a private repository. Create an empty private repository first if that applies to you, and never commit credentials or a raw account export.
git clone https://github.com/conorbronsdon/agent-context-os.git my-context
cd my-context
# Recommended for a private copy:
git remote rename origin upstream
git remote add origin <YOUR_PRIVATE_REPO_URL>
# Select every agent this repository will use:
bash scripts/setup.sh --agents claude,codex
# bash scripts/setup.sh --agents hermes
# bash scripts/setup.sh --agents openclaw
# bash scripts/setup.sh --agents cursor
# bash scripts/setup.sh --agents devin
# bash scripts/setup.sh --agents none # core-onlySetup presents an exact, digest-bound proposal before recording the selected
set. Reruns add agents but never remove them; use the explicit lifecycle to
disable one later. Omit the option, or use --agents auto, for local
auto-detection without changing repository intent. The singular --agent form
is a deprecated singleton alias. See workspace
configuration for the full contract.
After setup, bash scripts/contextos.sh agent list shows tracked activation and
local registration separately. agent enable (or agent add) creates an
additive proposal; agent disable creates the only proposal allowed to shrink
the set. Neither operation deletes bundled adapter files.
Then start your agent from the repository root. In the normal v0.12 full-template wrapper path, the product kernel, durable context, and nominal active work share one root. A marker-only JSON workspace may use an already-loaded executable package for discovery and reports, but a marker-only root cannot apply content or configure runtimes until the trusted product closure is materialized there. A containing Git worktree may supply read-only commit evidence without gaining context mutation authority. A separate application-repository attachment is not yet a supported lifecycle path; see the root contract.
| Starting point | Next action |
|---|---|
| New workspace in Claude Code | Run /setup |
| New workspace in Codex | Run $setup |
| New workspace in Hermes | Run /setup after exposing the repository skills |
| New workspace in OpenClaw | Follow the OpenClaw adapter, then run /contextos <alias> setup through an authorized operator surface |
| New workspace in Cursor | Follow the separate experimental IDE and CLI paths, then run /context-setup |
| New cloud session in Devin | Complete the managed-account checks, then run @skills:context-setup |
| Existing context in another assistant | Follow the migration guide, then use the selected material during setup |
| claude.ai only | Use SETUP-PROMPTS.md and copy the approved output into the repository |
The setup interview fills the identity, first project, workflows, and weekly state files. It can start from your answers or from a migration packet you reviewed first. See the full getting started guide for prerequisites, privacy choices, and verification.
/start in Claude Code or Hermes, /context-start in Cursor, $start in Codex,
/contextos <alias> start in OpenClaw, and @skills:context-start in a Devin session read your state,
priorities, decisions, blockers, and recent handoff. The result is grounded in
files rather than reconstructed from chat.
At the end, /end or $end proposes a handoff for review before it updates sessions/ and state/. The namespaced $context-end form remains supported.
The GIF is scripted with sample data. docs/start-demo.tape regenerates it, and docs/demo/start-session.sh contains the transcript. Neither reads your state or calls a model.
Start small. Use the core loop for a week, add one active project, then turn a repeated task into a skill when the repetition is clear.
| Moment | Claude Code | Codex | Hermes | OpenClaw | Cursor IDE/CLI (experimental) | Devin session (experimental) | Shared result |
|---|---|---|---|---|---|---|---|
| First run or major refresh | /setup |
$setup |
/setup |
/contextos <alias> setup |
/context-setup |
@skills:context-setup |
Reviewed context proposal |
| Start work | /start |
$start |
/start |
/contextos <alias> start |
/context-start |
@skills:context-start |
Read-only continuity inventory and briefing |
| Save a checkpoint | /update |
$update |
/update |
/contextos <alias> update |
/context-update |
@skills:context-update |
Hash-checked update and receipt |
| Finish work | /end |
$end |
/end |
/contextos <alias> end |
/context-end |
@skills:context-end |
Hash-checked handoff, decisions, and receipt |
OpenClaw setup, update, and end can require multiple operator turns. Resume the
owned workflow with /contextos <alias> continue <session-key> <response>, then
apply the independently reviewed proposal from a trusted shell; the OpenClaw
plugin itself exposes no apply command.
The namespaced $context-setup, $context-start, $context-update, and
$context-end invocations remain available for compatibility.
Claude Code also ships host-specific commands for capture, daily checks, recovery, context search, and auto-memory curation. The host boundary names what is portable and what is not.
Do not import an entire chat archive into active context. Use the migration guide to:
- select the assistant, project, or small set of conversations that contains useful context;
- produce an inventory or compact migration packet;
- classify each item as keep, verify, skip, or archive;
- map approved facts, decisions, projects, and workflows into canonical files; and
- validate the repository before committing.
The guide covers ChatGPT, Claude, Gemini Apps, Gemini CLI, and a generic path for other systems. Gemini CLI also has privacy-first $migrate-gemini and $mine-gemini-workflows skills for selected configuration and session evidence. Consumer Gemini CLI requests transitioned to Antigravity CLI in June 2026; continuing enterprise/API-key Gemini CLI and Antigravity are separate targets, and this repository does not claim Antigravity lifecycle or permission parity.
| Host | Tier | Support |
|---|---|---|
| Claude Code | first-class | Shared lifecycle, slash-command adapters, hooks, optional live reads, and Claude-only auto-memory curation |
| Codex | first-class | Shared lifecycle, native skills, project instructions, hooks, and reviewed proposal/apply writes |
| Cursor | experimental | Separate IDE and CLI onboarding through root AGENTS.md and project Agent Skills, without hook, memory, or rule-conflict claims |
| Devin | experimental | Experimental cloud-session lifecycle through repository AGENTS.md and Agent Skills, with Devin Review and all account-managed state kept separate |
| Hermes Agent | first-class | Shared lifecycle through portable skills, advisory hooks, MCP, and separate Hermes-native memory |
| OpenClaw | first-class | External-plugin multi-turn lifecycle with alias-bound lightweight subagents, copied portable skills, separate private memory, and trusted-shell kernel apply |
Compatibility paths that are not registered runtime adapters:
| Host | Compatibility path |
|---|---|
| Gemini CLI / Antigravity CLI | Migration tooling plus portable-skill discovery for continuing enterprise/API-key Gemini CLI; no complete workspace adapter, and no Antigravity discovery or permission parity is claimed |
| claude.ai | Manual consumer of selected knowledge files; no repository writes, hooks, or slash-command parity |
| Other agents | Can use the Markdown state and portable skills only when their file and Agent Skills support is compatible |
| Capability | Shared | Claude Code | Codex | Hermes | OpenClaw | Cursor IDE/CLI (experimental) | Devin session (experimental) |
|---|---|---|---|---|---|---|---|
| Identity, project, state, and session files | Yes | Reads | Reads | Reads | Reads | Reads | Reads |
| Deterministic proposal/apply and receipts | Yes | Adapter | Native skill calls | Installed skill calls | Copied skill calls | Native skill calls | Native skill calls |
| Lifecycle vocabulary | Semantics | /setup etc. |
$setup etc. |
/setup etc. |
/contextos <alias> setup etc. |
/context-setup etc. |
@skills:context-setup etc. |
| Project hooks | Event contract only | .claude/ |
.codex/ |
Optional adapter | Not claimed | Not claimed | Not claimed |
| Native memory | No | Claude auto-memory | Outside contract | MEMORY.md / USER.md |
Private workspace | Outside contract | Account-managed; not synchronized |
The shared layer is intentionally plain files. Provider-specific tool names, hooks, permissions, and memory features stay in their adapter directories.
The optional integrations catalog is generated from integrations/catalog.json. Each entry declares supported hosts, credentials, reads, writes, publish or destructive capabilities, confirmation gates, evidence, a health check, and uninstall behavior.
Start with the task-based integration chooser, add at most one new trust boundary at a time, then read the selected generated entry in full.
The current catalog includes portable skill collections and creator tools, plus reviewed paths for MarkItDown MCP, Tolaria MCP, Obsidian CLI, Beads for Gemini CLI, Granola MCP, Google Workspace CLI, Notion MCP, and Substack MCP. listed and experimental entries are leads, not endorsements. Setup never installs, authenticates, or activates them.
AGENTS.md Portable repository instructions
CLAUDE.md Claude Code root context and adapter index
ROUTING.md Task-to-context routing table
TODO.md Full backlog
identity/ Stable personal and professional context
projects/ Project context and project-specific workflows
state/ Current focus, priorities, blockers, and decisions
sessions/ Reviewed session handoffs
.agents/skills/ Provider-neutral workflow cores
contextos/ Deterministic lifecycle kernel
and offline bundle materializer
.claude/commands/ Claude Code slash-command adapters
.claude/skills/ Claude Code-only skills
.claude/hooks/ Claude Code-only safety and session hooks
.codex/hooks.json Codex lifecycle advisory adapter
adapters/hermes/ Hermes installation and optional hook adapter
adapters/openclaw/ First-class OpenClaw plugin and skills adapter
adapters/cursor/ Experimental Cursor IDE and CLI adapter
adapters/devin/ Experimental Devin session and Review adapter
runtimes/ Machine-readable capability manifests
components/ Component ownership and dependency manifest
bundles/ Generated detached bundle-lock schema
workspace/ Schema and inactive canonical config example
integrations/ Machine-checked opt-in integration catalog
references/ Generated catalog and integration setup notes
scripts/ Setup, validation, migration, and maintenance tools
docs/ Onboarding, architecture, safety, and migration guides
The workspace migration command can now create a digest-bound proposal for
contextos.workspace.json and, when applicable, retire legacy workspace.yaml
in the same recoverable transaction. Setup-time agent selection remains tracked
in #65. The template does not ship a live root file because that would override
an existing clone's legacy YAML before its migration is reviewed.
Once present, contextos.workspace.json is the provider-neutral root marker,
including for a marker-only workspace. Existing AGENTS.md plus state/ or
workspace.yaml roots remain discoverable. The nearest recognized root wins,
and discovery never climbs past a nested .git repository boundary; use
--root to choose an explicit discovery start when cwd is not the intended
starting point. Discovery may still ascend from that path to the nearest valid
root before a nested Git boundary.
Each fact should have one canonical home. ROUTING.md points an agent to the right file instead of copying the same context across prompts.
A skill is a Markdown workflow for a task you repeat. Provider-neutral skills belong in .agents/skills/<name>/SKILL.md. Claude Code can add a thin adapter under .claude/commands/; Codex discovers the repository skill directly. Build a first portable skill after the core loop is working, or follow the portable skill structure for a shared workflow.
Claude Code auto-memory is a separate, host-specific layer. The repository includes a typed auto-memory specification and the /dream curator, which creates proposals before anything writes back. Shared continuity still belongs in state/ and sessions/ so another supported agent can use it.
- Review generated context before writing or committing it.
- Keep raw exports, credentials, private reasoning, and migration scratch data outside tracked files.
- Treat integrations as disabled until you choose and configure one.
- Use one git worktree per concurrent agent session.
- Follow
docs/safety-contract.mdbefore external writes, destructive actions, or permission changes.
Run the full local check after changing instructions, skills, scripts, adapters, generated references, or tracked personal context:
bash scripts/validate-all.sh --workspaceThe workspace mode permits new tracked files only below the component catalog's
declared extensible roots. CI and product contributors run the strict form
without --workspace, so every tracked template file still requires an owner.
Both forms check structure, adapter mappings, links, shell syntax, hook behavior,
JSON, tests, and generated integration documentation. They cannot prove the
behavior of an installed agent version or an external service.
| Goal | Guide |
|---|---|
| Install and choose a host | Getting started |
| Understand agent selection and legacy migration | Workspace configuration |
| Import useful context from another system | Migration guide |
| Use the repository in Codex | Codex onboarding |
| Use the repository in Hermes Agent | Memory across agents and the Hermes section of AGENTS.md |
| Use the repository in OpenClaw | OpenClaw adapter |
| Use the repository in Cursor | Experimental Cursor IDE and CLI adapter |
| Keep claude.ai projects aligned | Claude projects sync |
| See every command and portable skill | Commands and skills |
| Understand component ownership and future clean composition | Component model |
| Verify an offline bundle or inspect a structural plan | Bundle locks and plans |
| Understand KernelRoot, ContextRoot, WorkingRoot, and the v0.12 compatibility boundary | Root contract |
| Choose an optional add-on | Integration chooser and catalog |
| Understand product language and boundaries | Positioning |
| Keep context files small and cheap to load | Optimizing context files |
| Keep optional MCP calls inside a token budget | MCP efficiency |
| Maintain workspace context and memory | Workspace maintenance |
| Maintain the repository | Repository maintenance |
This is a template. Structural contributions, clearer conventions, reusable skills, and integration catalog entries are welcome. Open an issue with the pattern and the problem it solves.
See CONTRIBUTING.md for setup, the validator, generated files, and conventions, and SECURITY.md to report a vulnerability privately. Issues labelled good first issue need no external account or credential.
- Conor Bronsdon, host of the Chain of Thought podcast
Using the template? Open a PR to add yourself.
This is an independent personal project. It is not affiliated with, sponsored by, or endorsed by Anthropic, OpenAI, Google, or another provider.
MIT. See LICENSE. Fork it, adapt it, and make it yours. Attribution is not required.