Contextuate

What is Contextuate?

Contextuate provides a structured "brain" for your project that AI coding assistants (like Claude, Copilot, Cursor) can understand. It standardizes how AI agents receive context, follow coding standards, and execute tasks.

Discovery

The AI reads docs/ai/.contextuate/contextuate.md first. This file bootstraps the framework and links to project context.

Specialization

If acting as a specific agent, it reads docs/ai/agents/ to load specific capabilities and rules.

Execution

The AI follows the linked standards in docs/ai/standards/ and uses docs/ai/quickrefs/ for technical lookups.

Quick Start

One-Line Install (Recommended)

curl -fsSL https://contextuate.md/install.sh | sh

Install via npm

npm install -g @esotech/contextuate

Or use directly with npx:

npx @esotech/contextuate init

Install from Source

Clone the repository and install globally:

git clone https://github.com/esotech/contextuate.git
cd contextuate
npm install
npm run build
npm link

Initialize Your Project

Navigate to your project directory and run:

contextuate init

The interactive installer will guide you through selecting AI platforms, creating directory structures, and generating configuration files.

CLI Usage

Running Agents

Execute an agent definition with the run command:

contextuate run <agent-name> [options]

Power User Tip: The run command is designed to be used by both humans and AI agents. Agents can use it to spawn sub-agents to handle complex sub-tasks in parallel (e.g., "Run a dedicated bug-fixer agent on this file").

Example:

contextuate run documentation-expert --task api-refactor --goal "Update API docs" --isolation worktree

Context Management

Generate a token-optimized map of your codebase:

contextuate index

Interactively add files to your main context:

contextuate add-context

Agent Management

Scaffold a new agent definition:

contextuate create-agent <name>

Cleanup

Safely remove framework files (only unmodified ones):

contextuate remove