conorbronsdon/claude-context-os

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 and Codex read the same repository state. Git shows what changed. A reviewed start, checkpoint, and close loop keeps the context current without treating an assistant's private memory as the source of truth.

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.

Quick start

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/claude-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>

# Pick a host, or omit --agent to auto-detect one:
bash scripts/setup.sh --agent claude
# bash scripts/setup.sh --agent codex

Then start your agent from the repository root:

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 and $context-start in Codex read your state, priorities, decisions, blockers, and recent handoff. The result is a working briefing grounded in files, not a request to reconstruct everything from chat.

At the end, /end or $context-end proposes a handoff for review before it updates sessions/ and state/.

_{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.

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

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

Repository layout

AGENTS.md                  Codex 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
.claude/commands/          Claude Code slash-command adapters
.claude/skills/            Claude Code-only skills
.claude/hooks/             Claude Code-only safety and session hooks
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

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, or generated references:

bash scripts/validate-all.sh

CI runs the same aggregate validator. It checks structure, adapter mappings, links, shell syntax, hook behavior, JSON, tests, and generated integration documentation. It cannot prove the behavior of an installed agent version or an external service.

Documentation

Contributing

This is a template. Structural contributions, clearer conventions, and reusable skills are welcome. Open an issue with the pattern and the problem it solves.

Used by

• Conor Bronsdon, host of the Chain of Thought podcast

Using the template? Open a PR to add yourself.

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.