Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/goca-se/dotcontext

AI context toolkit for Claude Code — commands, decisions, skills, and feature planning for your codebase
https://github.com/goca-se/dotcontext

ai-assistant ai-coding ai-context claude claude-code cli context-management developer-tools toolkit

Last synced: 1 day ago
JSON representation

AI context toolkit for Claude Code — commands, decisions, skills, and feature planning for your codebase

Awesome Lists containing this project

README 

          


  dotcontext logo




dotcontext





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






  Release

  License




`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





  dotcontext quick start demo




## Installation



```bash

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

```



Or manually:



```bash

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



```bash

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:**



```bash

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



```bash

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):



```bash

claude

> /setup-context

```



See it in action



setup-context demo



## 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:



1. **Stop and inform you** which decision(s) would be affected

2. **Ask explicitly** if you want to:

   - Proceed and update the decision

   - Modify the approach to comply

   - Cancel the change

3. **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](#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](https://github.com/upstash/context7-mcp) — up-to-date library docs for LLMs

  - [Atlassian](https://mcp.atlassian.com) — 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/`:



```bash

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](https://github.com/anthropics/claude-code/tree/main/plugins/code-review):



**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:**

```bash

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



```text

/spec-dc  (the WHAT)  →  /plan-dc  (the HOW)  →  /execute-dc  (the DO)

   spec file               plan file              implemented + reviewed

```



#### `/spec-dc `



Writes a **behavior specification** — the WHAT — into `.context/specs/spec--.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)



```text

> /spec-dc user authentication with OAuth

```



#### `/plan-dc `



Turns a spec into a precise **implementation plan** — the HOW — in `.context/plans/plan--.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`



```text

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

```



#### `/execute-dc `



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



```text

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

# 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



```bash

rm /usr/local/bin/dotcontext

```