Core Concepts

The Library

ContextMark stores all your Claude Code configs in a central library at ~/.contextmark/. This library acts as a single source of truth for all your projects and can be synced across machines via Git.

Per-Project Configs

Each project's CLAUDE.md and .claude/ directory are stored in ~/.contextmark/projects/.

Global Config

Your global ~/.claude/ config (CLAUDE.md, rules/, skills/) is stored in ~/.contextmark/global/.

Push/Pull Workflow

ContextMark uses a simple push/pull workflow similar to Git. Save your configs to the library, then restore them on any machine.

Push

Copy your local CLAUDE.md and .claude/ to the library. Use --global for ~/.claude/.

contextmark push

Pull

Restore configs from the library to your local project. Use --global for ~/.claude/.

contextmark pull

Diff & Status

Check what's changed between your local configs and the library.

Diff

Compare local files with library versions. Shows exactly what's different.

contextmark diff

Status

Quick overview of sync status for the current project or all projects.

contextmark status --all

Git Synchronization

Keep your library in sync across machines using Git. The library itself is a Git repository that can be pushed to any remote (GitHub, GitLab, Bitbucket, etc.).

Sync Push

Commit and push library changes to the remote repository.

contextmark sync push

Sync Pull

Pull the latest library changes from the remote repository.

contextmark sync pull

Library Structure

~/.contextmark/

├── config.yml # Global configuration

├── projects/ # Per-project configs

│ ├── my-project/

│ │ ├── CLAUDE.md

│ │ └── .claude/

│ └── another-project/

│ └── CLAUDE.md

├── global/ # Global ~/.claude/ backup

│ ├── CLAUDE.md

│ ├── rules/

│ └── skills/

├── blocks/ # (Advanced) Reusable blocks

├── profiles/ # (Advanced) Block combinations

├── agents/ # Reusable agents

└── commands/ # Custom commands

Agents & Commands

Store reusable agents and commands in your library, then add them to any project.

Agents

AI assistant configurations stored as Markdown. Add to projects with contextmark add-agent.

Commands

Slash command definitions for Claude Code. Add to projects with contextmark add-command.

Advanced: Blocks & Profiles

For power users who want to compose CLAUDE.md from reusable pieces instead of syncing whole files.

Blocks

Reusable context snippets stored as Markdown with YAML frontmatter. Each block focuses on a specific topic.

---
name: Laravel Base
description: Laravel framework conventions
version: 1.0.0
---

## Laravel Conventions

- Use Form Requests for validation
- Keep controllers thin

Profiles

YAML files that combine multiple blocks. Use with contextmark init --profile to generate CLAUDE.md.

name: Laravel Package
description: For Laravel packages
blocks:
  - laravel/base
  - style/code
agents:
  - reviewer