A portable, evolving Git-backed context and workflow layer for coding agents. Claude Code, Codex, OpenClaw, and OpenCode are first-class; Hermes Agent, Cursor, and Devin adapters are experimental.
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, OpenClaw, and OpenCode, plus the experimental Hermes, 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.
For a small project, try keeping the objective, decisions, and latest handoff in one instruction file. If separate notes help you review that context, the experimental three-file starter provides copyable instructions, current work, and a handoff. It needs a file-capable agent and manual review, with no installer or runtime registration.
The starter has not been established as the preferred default. Read the evidence and limits, then try the one-week comparison. Existing full-template users should keep their current workflow and evaluate the starter in a separate project.
Try your first reviewed handoff for a small Claude-to-Codex example. Then inspect source briefings and change history.
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 opencode
# 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.
For a separate application repository, pass exact distinct roots and create a reviewable attachment proposal (global role options precede the command):
bash /path/to/context-os/scripts/contextos.sh \
--context-root /path/to/context-repo \
--working-root /path/to/application \
project attach --id my-appApply the returned digest with the same root options and --runtime generic.
Later start/setup/update/end invocations use those exact roots. Context OS writes
only ContextRoot; WorkingRoot contributes bounded Git identity, status, and
history evidence and receives no marker or lifecycle file. A moved application
requires a reviewed project rebind --id my-app proposal. See the root
contract.
| Starting point | Next action |
|---|---|
| New workspace in Claude Code | Run /setup |
| New workspace in Codex | Run $setup |
| New workspace in experimental Hermes support | Read the evidence limit, then 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 OpenCode | Follow the OpenCode adapter, then run /context-setup from the repository root |
| 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 or OpenCode, $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 | OpenCode | Hermes (experimental) | OpenClaw | Cursor IDE/CLI (experimental) | Devin session (experimental) | Shared result |
|---|---|---|---|---|---|---|---|---|
| First run or major refresh | /setup |
$setup |
/context-setup |
/setup |
/contextos <alias> setup |
/context-setup |
@skills:context-setup |
Reviewed context proposal |
| Start work | /start |
$start |
/context-start |
/start |
/contextos <alias> start |
/context-start |
@skills:context-start |
Read-only continuity inventory and briefing |
| Save a checkpoint | /update |
$update |
/context-update |
/update |
/contextos <alias> update |
/context-update |
@skills:context-update |
Hash-checked update and receipt |
| Finish work | /end |
$end |
/context-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 | experimental | Deterministic adapter and kernel conformance; installed-client model inference remains unverified, with advisory hooks and separate 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 |
| OpenCode | first-class | Repository-native AGENTS.md and Agent Skills discovery with typed lifecycle commands, native permissions, and deterministic proposal/apply safety |
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 | OpenCode | Hermes (experimental) | OpenClaw | Cursor IDE/CLI (experimental) | Devin session (experimental) |
|---|---|---|---|---|---|---|---|---|
| Identity, project, state, and session files | Yes | Reads | Reads | Reads | Reads | Reads | Reads | Reads |
| Deterministic proposal/apply and receipts | Yes | Adapter | Native skill calls | Typed command + native skill | Installed skill calls | Copied skill calls | Native skill calls | Native skill calls |
| Lifecycle vocabulary | Semantics | /setup etc. |
$setup etc. |
/context-setup etc. |
/setup etc. |
/contextos <alias> setup etc. |
/context-setup etc. |
@skills:context-setup etc. |
| Project hooks | Event contract only | .claude/ |
.codex/ |
Not claimed | Optional adapter | Not claimed | Not claimed | Not claimed |
| Native memory | No | Claude auto-memory | Outside contract | 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 and its
machine-readable aggregate are generated from
entry-local sources in integrations/entries/. 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.
Maintainers can run python3 scripts/integrations.py freshness to see which
entries are approaching or past their human evidence-review date. Pass
--as-of YYYY-MM-DD when reproducible output is required.
The catalog spans portable skill collections, creator tools, CLIs, and MCP
servers. Treat the generated catalog and task-based chooser as the current
inventory rather than relying on a hand-maintained summary. 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
coordination/ Multi-run message board contract; the board itself
lives on a dedicated coordination branch
.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
.opencode/commands/ OpenCode typed lifecycle adapters
adapters/hermes/ Hermes installation and optional hook adapter
adapters/openclaw/ First-class OpenClaw plugin and skills adapter
adapters/opencode/ First-class OpenCode onboarding and conformance
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 OpenCode | OpenCode 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 the composition/materialization substrate | Component model |
| Verify an offline bundle or inspect a structural plan | Bundle locks and plans |
| Read release scope and evidence limits | v0.13.1 release notes; v0.12.0 archive |
| 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
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.