agent-context-os

Context OS

Keep durable project context and workflows in a Git-backed repository that supported coding agents can read and update through reviewed handoffs.

Chat history, project instructions, and copied prompts drift apart. Context OS is a Git-backed context and workflow layer that keeps 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, OpenCode, Cursor CLI, Devin CLI, and Hermes Agent have first-class adapters, and Devin cloud sessions are first-class too. Cursor IDE remains experimental; their available surfaces and evidence limits are listed in host support. These adapters route to shared repository state, with a deterministic lifecycle kernel that turns reviewed setup, checkpoint, and close requests into hash-checked proposals and receipts. Host-native memory stays separate.

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.

Experimental starter for one project

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.

Quick start

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.

Start from a published release

Source version 1.2.0 is a candidate until its immutable release is published. Until then, v1.1.1 is the latest published release.

For a version-pinned workspace, open v1.2.0 and download all five attached assets: the template .tar, bundle lock, provenance, OFFLINE-VERIFY.md, and SHA256SUMS. Follow that release's agent-context-os-template-v1.2.0.OFFLINE-VERIFY.md to verify the assets before extracting and running setup. GitHub's generated source ZIP and tar.gz are repository snapshots; the attached template tar is the canonical workspace. Use the v1.2.0 release notes for what that version ships. Changes and support promotions described on a development branch may require a later release.

Initialize your own Git repository inside the verified extracted workspace before running setup (git init). This gives its hooks and Git evidence an independent boundary. The first reviewed handoff covers release verification and a local synthetic exercise.

Version 1.2.0 adds first-class Devin cloud sessions and native Windows Devin CLI support. If it is not published yet, use v1.1.1 or the source setup path below.

Start from source

Clone the source when you want the current branch and its development tools:

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-only

Setup 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-app

Apply 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.

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.

See the loop

/start in Claude Code, /context-start in Hermes, Cursor, Devin CLI, 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.

Daily workflow

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.

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.

Bring existing context with you

Do not import an entire chat archive into active context. Use the migration guide to:

1. select the assistant, project, or small set of conversations that contains useful context;
2. produce an inventory or compact migration packet;
3. classify each item as keep, verify, skip, or archive;
4. map approved facts, decisions, projects, and workflows into canonical files; and
5. 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 support

Compatibility paths that are not registered runtime adapters:

One source, explicit host adapters

The shared layer is intentionally plain files. Provider-specific tool names, hooks, permissions, and memory features stay in their adapter directories.

Optional integrations

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.

Repository layout

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/           First-class Cursor CLI and experimental IDE adapter
adapters/devin/            First-class Devin CLI and cloud-session adapter, plus Review
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.

Skills and memory

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.

Safety and validation

• 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.md before 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 --workspace

The 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.

Documentation

Contributing

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.

Created By

• Conor Bronsdon, host of the Chain of Thought podcast

Disclaimer

This is an independent personal project. It is not affiliated with, sponsored by, or endorsed by Anthropic, OpenAI, Google, or another provider.

License

MIT. See LICENSE. Fork it, adapt it, and make it yours. Attribution is not required.