dotcontext

AI context toolkit for coding agents — Claude Code, Codex, opencode, Gemini, Copilot & Cursor

dotcontext is an AI context toolkit for coding agents — Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, and Cursor. It provides commands, decisions, skills, and feature planning workflows that help AI assistants understand and work with your codebase.

See it in action

Installation

curl -sSL https://raw.githubusercontent.com/goca-se/dotcontext/main/install.sh | bash

Or manually:

curl -sSL https://raw.githubusercontent.com/goca-se/dotcontext/main/dotcontext -o /usr/local/bin/dotcontext
chmod +x /usr/local/bin/dotcontext

Usage

Initialize a project

cd your-project
dotcontext init

This creates the context structure and downloads templates for the harness(es) you select. When Claude Code is among them, it automatically opens Claude running /setup-context to analyze and populate your project's context files; otherwise, edit AGENTS.md and .context/CONTEXT.md to describe your project.

Options:

dotcontext init --name "My Project"  # Set project name
dotcontext init --yes                # Skip prompts, use defaults
dotcontext init --no-setup           # Skip automatic /setup-context execution

Update

dotcontext update                  # Update CLI + templates (if in a project)
dotcontext update --cli            # Only update CLI
dotcontext update --templates      # Only update templates
dotcontext update --dry-run        # Preview template changes only
dotcontext update --yes            # Update templates without prompting

Terraform-style preview for templates:

Checking templates...

  + .claude/commands/fix-bug.md (new)
  ~ .claude/commands/code-review.md (modified)
  = .claude/commands/setup-context.md (unchanged)
  • .claude/skills/bug-reproduction/SKILL.md (user-managed — skipped)

Summary: 1 to add, 1 to update, 8 unchanged, 1 user-managed

Update 1 existing file(s)? [y/N/d] (y=yes, N=no, d=show diffs)

Safe by default:

CLI downloads from the release tag (not main branch) — no unreleased code
Templates show exactly what will change before doing anything
Default action (N) only adds new files, never overwrites
Press d to see diffs before deciding
User-managed files (skills, READMEs) are never overwritten — they're created once during init and then owned by you
Never touches user content (CONTEXT.md, CLAUDE.md, your ADRs, bug reports, discoveries)

Run the setup command

The setup command runs automatically after dotcontext init. To run it manually (e.g., after code changes):

claude
> /setup-context

See it in action

Decision Compliance

The generated AGENTS.md (the canonical instructions file) includes instructions for AI assistants to respect architectural decisions.

When you ask Claude Code to make a change that conflicts with an existing ADR, it will:

Stop and inform you which decision(s) would be affected
Ask explicitly if you want to:
- Proceed and update the decision
- Modify the approach to comply
- Cancel the change
If updating, create a versioned ADR (marking old one as Superseded)

This ensures your architectural decisions stay synchronized with your code.

What It Creates

your-project/
├── AGENTS.md                    # Canonical project instructions (read by Codex, opencode, Copilot, Cursor…)
├── CLAUDE.md                    # Thin @AGENTS.md import for Claude Code (always added for compatibility)
├── GEMINI.md                    # Thin @AGENTS.md import for Gemini CLI (added when Gemini is detected)
├── .context/
│   ├── CONTEXT.md               # Domain knowledge
│   ├── decisions/               # ADRs (versioned)
│   ├── discoveries/             # Deep context analysis outputs
│   ├── bugs/                    # Bug fix reports
│   ├── specs/                   # Behavior specs — the WHAT (/spec-dc)
│   └── plans/                   # Implementation plans — the HOW (/plan-dc)
├── .mcp.json                    # MCP server config (Context7, Atlassian)
└── .claude/
    ├── commands/
    │   ├── setup-context.md          # Auto-setup command
    │   ├── code-review.md            # Code review command
    │   ├── commit.md                 # Smart commit command
    │   ├── spec-dc.md                # Write a behavior spec (the WHAT)
    │   ├── plan-dc.md                # Turn a spec into a plan (the HOW)
    │   ├── execute-dc.md             # Implement a plan in waves (the DO)
    │   ├── create-pr.md              # Create PRs with diagrams
    │   ├── pr-comment.md             # Comment on PRs
    │   ├── add-decision.md           # Add ADR interactively
    │   ├── add-skill.md              # Add skill interactively
    │   ├── add-command.md            # Add custom command
    │   ├── deep-context.md           # Structured codebase exploration
    │   └── fix-bug.md               # Test-driven bug fixing
    ├── agents/                       # Extracted agent prompts
    │   ├── code-review/              # 3 review agents
    │   ├── deep-context/             # 4 exploration agents
    │   ├── fix-bug/                  # 5 bug-fix agents
    │   ├── spec-dc/                  # 2 spec reviewers (pro + fast)
    │   ├── plan-dc/                  # 2 plan reviewers (pro + fast)
    │   └── execute-dc/               # 2 implementation reviewers (pro + fast)
    ├── skills/                       # Step-by-step guides (SKILL.md w/ name+description frontmatter)
    │   ├── bug-reproduction/         # Reproduce-before-fixing patterns
    │   ├── batch-operations/         # Safe multi-file changes
    │   ├── git-platform/             # Detect GitHub/GitLab/… before git CLI
    │   └── update-api-documentation/ # OpenAPI SSOT docs
    └── scripts/
        └── statusline.sh            # StatusLine: model, dir, git, ctx-usage bar, cost/time/lines

Files are emitted per chosen harness (see Multi-Agent Support): AGENTS.md and .context/ are always written; the full .claude/ tree and CLAUDE.md appear only when Claude is selected, GEMINI.md only for Gemini, and .agents/skills/ only when a non-Claude agent is selected.

Additionally, dotcontext init configures:

MCP servers in .mcp.json (optional, prompted during init):
- Context7 — up-to-date library docs for LLMs
- Atlassian — Jira + Confluence via OAuth
Native OS notifications in .claude/ (project-local):

.claude/
├── scripts/
│   └── notify.sh          # Cross-platform notification script
└── settings.json          # Hooks for Notification and Stop events

Multi-Agent Support

dotcontext works with six harnesses: Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, and Cursor (IDE and cursor-agent). init only writes files for the harnesses you pick, so a Codex-only project never ends up with a stray .claude/:

dotcontext init                       # interactive: confirm each detected agent
dotcontext init --agents codex,cursor # explicit, non-interactive
dotcontext init --yes                 # all detected agents

What's shared vs per-harness (ADR-016, ADR-017):

Layer	Coverage
Instructions (`AGENTS.md`)	Codex, opencode, Copilot, and Cursor read it natively; Claude (`CLAUDE.md`) and Gemini (`GEMINI.md`) import it with `@AGENTS.md`
Skills (`SKILL.md`)	`.agents/skills/` for Codex/opencode/Gemini/Copilot/Cursor, mirrored to `.claude/skills/` for Claude
Hooks (finish notification)	native config per harness (`.codex/`, `.gemini/`, `.github/hooks/`, `.cursor/`, opencode plugin); Claude also gets the tool-failure guard
Commands / workflows	Claude `.claude/commands/`, opencode `.opencode/command/`, Copilot `.github/prompts/`; Gemini, Cursor, and Codex use the `## Workflows` section of `AGENTS.md`

dotcontext update migrates an existing single-file CLAUDE.md into the shared AGENTS.md (Claude keeps working via the import). Check dotcontext --version --json for the live capability/agent list.

Commands Reference

CLI Commands

Command	Description
`dotcontext init`	Initialize + auto-run /setup-context
`dotcontext init --no-setup`	Initialize without running setup
`dotcontext update`	Update CLI + templates (if in a project)
`dotcontext update --cli`	Only update CLI
`dotcontext update --templates`	Only update templates
`dotcontext update --yes`	Update templates without prompting
`dotcontext update --dry-run`	Preview template changes only
`dotcontext doctor`	Check project setup health (+ flags available updates)
`dotcontext completion [bash\|zsh]`	Generate shell tab completions
`dotcontext --help`	Show help
`dotcontext --version [--features\|--json]`	Show version; `--features`/`--json` expose the capability handshake

Claude Code Commands

Command	Description
`/setup-context`	Analyze codebase and populate context
`/spec-dc [feature]`	Write a behavior spec — the WHAT (step 1)
`/plan-dc [spec-path]`	Turn a spec into a plan with ADR review — the HOW (step 2)
`/execute-dc [plan-path]`	Implement a plan in parallel waves — the DO (step 3)
`/code-review [--comment]`	Multi-agent code review with confidence scoring
`/commit [--amend]`	Smart commit with style-aware message generation
`/create-pr`	Create PR with auto-detected architecture diagrams
`/pr-comment [PR] [message]`	Add comments to PRs with optional diagrams
`/deep-context [query]`	Structured 4-step codebase exploration
`/fix-bug [description]`	Test-driven bug fixing with parallel agents
`/add-decision`	Add and populate an ADR interactively
`/add-skill`	Add and populate a skill guide
`/add-command`	Create a custom slash command
`/release`	Version bump and release

Built-in Slash Commands

`/setup-context`

Analyzes your codebase and populates context files:

Fills CLAUDE.md with stack, commands, rules
Documents domain in .context/CONTEXT.md
Generates Architecture section — system overview, directory structure, key dependencies, data flow
Detects coding conventions — adaptive sampling (5-20 files based on project size) across 6 categories: naming patterns, error handling, testing style, import organization, state management, API response format
Creates ADRs for existing architectural decisions
Sets up skills for recurring patterns

`/code-review [--comment]`

Multi-agent code review inspired by Claude Code's official plugin:

Architecture:

Launches 4 parallel agents for independent analysis:
- 2x CLAUDE.md compliance checkers (redundancy)
- 1x Bug detector (logic errors, edge cases, type mismatches)
- 1x Security & history analyzer (vulnerabilities + git blame patterns)
Confidence scoring (0-100) filters false positives (threshold ≥80)
Automatic context gathering (CLAUDE.md files + PR diff)

Usage:

/code-review           # Review to terminal
/code-review --comment # Post review as PR comment

Pre-flight checks (auto-skips):

Closed or merged PRs
Draft PRs
PRs already reviewed by this tool
Trivial changes (whitespace only)

Review categories:

Correctness and edge cases
Security vulnerabilities (OWASP top 10)
Performance issues
Code quality and patterns
CLAUDE.md rule violations

Feature development: spec → plan → execute

Feature work runs as a three-command pipeline. Each step produces a durable, versioned artifact that the next step consumes — the spec is the source of truth the plan is measured against, and the plan is the contract the implementation is measured against.

/spec-dc  (the WHAT)  →  /plan-dc  (the HOW)  →  /execute-dc  (the DO)
   spec file               plan file              implemented + reviewed

`/spec-dc <feature description>`

Writes a behavior specification — the WHAT — into .context/specs/spec-<unix-ts>-<slug>.md:

Runs a clarity assessment and asks only the targeted questions that genuinely unblock ambiguity
Researches the real codebase (delegates broad sweeps to parallel Explore subagents)
Produces seven mandatory sections (user stories, success criteria, functional & non-functional requirements, constraints/out-of-scope, technical context, acceptance tests)
Describes observable behavior only — no code, no implementation plan, no ADR review
Closes with a dual reviewer loop (spec-dc/reviewer-pro + reviewer-fast) that checks well-formedness, testability, scope, grounding, and fidelity to the request — not product merit (that stays your call)

> /spec-dc user authentication with OAuth

`/plan-dc <spec-path>`

Turns a spec into a precise implementation plan — the HOW — in .context/plans/plan-<unix-ts>-<slug>.md:

Reads the spec (source of truth) and the actual code
Owns the ADR review for the whole flow — checks .context/decisions/, records impact, flags conflicts
Lists exact files to create/modify, tests, verification/regression, and a 100% Traceability table proving every spec item is covered
Runs a dual adversarial review loop (Reviewer Pro + Reviewer Fast, in parallel) until double-APPROVED

> /plan-dc .context/specs/spec-1746500000-user-auth.md

`/execute-dc <plan-path>`

Implements an approved plan — the DO — treating the plan as an immutable contract:

Git hygiene: branches from the repo's detected base branch; offers worktree isolation
Decomposes the plan into parallel waves (disjoint files per wave, up to 3 subagents at a time)
Runs the project's tests after each wave; stops and fixes before advancing
Closes with a dual review of the git diff against the plan
Knowledge reconciliation back into CONTEXT.md/ADRs/skills is a deferred final step (ADR-019)

Branch types are auto-detected from the plan: feature/, bugfix/, hotfix/, chore/, experiment/.

> /execute-dc .context/plans/plan-1746500123-user-auth.md

# Optionally creates: ../your-project-user-auth (branch: feature/user-auth)

`/create-pr`

Create well-structured pull requests with automatic architecture diagram detection:

Analyzes all commits since branching from main
Generates appropriate PR title and description
Auto-detects architectural changes and suggests Mermaid diagrams:
- New services/components → flowchart
- API changes → sequence diagram
- Data flow changes → flowchart
- Database changes → ER diagram
Pushes branch with confirmation if not on remote
Respects existing PR templates (.github/PULL_REQUEST_TEMPLATE.md)

Example:

> /create-pr

# Analyzes changes, detects new API endpoint
# Generates PR with sequence diagram showing request flow

`/pr-comment [PR] [message]`

Add comments to existing pull requests:

Comment types:
- General comment - conversation thread
- Review comment - formal review
- Diagram explanation - architecture with Mermaid
- Status update - progress tracking
Auto-detects PR from current branch if not specified
Generates Mermaid diagrams when discussing architecture
Integrates with /code-review for follow-up

Example:

> /pr-comment add diagram explaining the new auth flow
> /pr-comment 123 LGTM, tested locally
> /pr-comment update status - frontend complete

`/deep-context [query]`

Structured 4-step codebase exploration with specialized agents:

Architecture:

Follows a structured progression from high-level to detailed:
- Step 1: Overview Agent — architecture summary, key files, entry points
- Step 2: Subsystem Agent — module map, interdependencies, boundaries
- Step 3: Drill Agent — targeted deep-dive into relevant areas
- Step 4: Data Flow Agent — trace information movement through the system
Phased execution: Steps 1+2 run in parallel, Steps 3+4 run sequentially (each builds on prior outputs)
Confidence filtering: findings below 50% are auto-removed

Features:

Auto-detects related repos from .context/CONTEXT.md external integrations
--repo flag for manual repo specification (local path or git URL)
--cache flag to reference previous discoveries
Every finding backed by file:line references (no fabrication)
Output saved to .context/discoveries/

Usage:

> /deep-context "checkout flow"
> /deep-context "payment rules" --repo ~/path/to/api
> /deep-context "order processing" --cache

`/fix-bug [description]`

Test-driven bug fixing with parallel subagents:

Architecture:

Phase 1 — Investigation: Agent analyzes the bug, identifies root cause, writes a failing test
Phase 2 — Parallel Fixes: N agents (default 3) attempt fixes with diverse strategies:
- Conservative (minimal diff)
- Minimal change (surgical, exact lines)
- Refactor (fix + improve surrounding code)
Phase 3 — Review: Reviewer agent selects best fix or combines multiple successful fixes
All agents run to completion (best fix, not just first fix)

Features:

Zero questions — goes straight from description to investigation
Test-first: writes a failing test before any fix attempt
--issue N to include GitHub issue context
--pr N to include PR context
--agents N to configure parallel fix agents
Bug report saved to .context/bugs/
Includes bug-reproduction skill template for project-specific patterns

Usage:

> /fix-bug "login fails with empty password"
> /fix-bug "checkout timeout" --issue 42
> /fix-bug "regression in search" --pr 123 --agents 5

`/add-decision [title]`

Interactively create and populate an Architectural Decision Record:

Asks clarifying questions about context and alternatives
Auto-numbers the ADR (001, 002, ...)
Populates with structured content
Updates the decisions index

`/add-skill [name]`

Interactively create and populate a skill guide:

Analyzes codebase for existing patterns
Asks about use cases and anti-patterns
Includes real code examples from your project
Creates step-by-step documentation

`/add-command [name]`

Create a custom Claude Code slash command:

Asks about command purpose and behavior
Generates command file with proper structure
Immediately available as /your-command

Notifications

dotcontext init automatically configures native OS notifications for each selected harness in its own hook config (.claude/settings.json, .codex/hooks.json, .gemini/settings.json, .github/hooks/, .cursor/hooks.json, or an opencode plugin). For Claude:

Event	When	Sound (macOS)
Notification	Claude needs attention (question, permission)	Purr
Stop	Claude finished processing	Funk

Supported platforms:

macOS: Native notifications via osascript
Linux: notify-send + paplay/aplay
Windows/WSL: PowerShell toast notifications

No additional dependencies required.

Shell Completion

dotcontext init offers to wire this into your shell profile automatically. To set it up manually instead:

# Bash (add to ~/.bashrc)
eval "$(dotcontext completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(dotcontext completion zsh)"

Completes subcommands (init, update, doctor, completion) and per-command options.

Requirements

Bash 3.2+
curl or wget

Uninstall

rm /usr/local/bin/dotcontext

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.claude		.claude
.context		.context
.github		.github
assets		assets
scripts		scripts
src		src
templates		templates
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
dotcontext		dotcontext
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

dotcontext

Installation

Usage

Initialize a project

Update

Run the setup command

Decision Compliance

What It Creates

Multi-Agent Support

Commands Reference

CLI Commands

Claude Code Commands

Built-in Slash Commands

`/setup-context`

`/code-review [--comment]`

Feature development: spec → plan → execute

`/spec-dc <feature description>`

`/plan-dc <spec-path>`

`/execute-dc <plan-path>`

`/create-pr`

`/pr-comment [PR] [message]`

`/deep-context [query]`

`/fix-bug [description]`

`/add-decision [title]`

`/add-skill [name]`

`/add-command [name]`

Notifications

Shell Completion

Requirements

Uninstall

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

dotcontext

Installation

Usage

Initialize a project

Update

Run the setup command

Decision Compliance

What It Creates

Multi-Agent Support

Commands Reference

CLI Commands

Claude Code Commands

Built-in Slash Commands

/setup-context

/code-review [--comment]

Feature development: spec → plan → execute

/spec-dc <feature description>

/plan-dc <spec-path>

/execute-dc <plan-path>

/create-pr

/pr-comment [PR] [message]

/deep-context [query]

/fix-bug [description]

/add-decision [title]

/add-skill [name]

/add-command [name]

Notifications

Shell Completion

Requirements

Uninstall

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`/setup-context`

`/code-review [--comment]`

`/spec-dc <feature description>`

`/plan-dc <spec-path>`

`/execute-dc <plan-path>`

`/create-pr`

`/pr-comment [PR] [message]`

`/deep-context [query]`

`/fix-bug [description]`

`/add-decision [title]`

`/add-skill [name]`

`/add-command [name]`