Skip to content

esotech/contextuate

BranchesTags

Repository files navigation

Contextuate Framework

Contextuate Logo

Standardized AI Context for Software Projects

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.

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:

  1. Selecting which AI platforms to configure (Claude Code, Cursor, Copilot, Windsurf, etc.)
  2. Creating the docs/ai/ directory structure with framework files
  3. Generating platform-specific configuration files
  4. Setting up symlinks for supported platforms (e.g., .claude/ for Claude Code)

What is Contextuate?

Contextuate is a directory structure and set of conventions that helps AI agents work more effectively. It turns implicit project knowledge into explicit, structured context.

  • docs/ai/.contextuate/contextuate.md: The framework bootstrap file. It links to everything else.
  • docs/ai/context.md: Your project-specific context (Identity, Tech Stack).
  • docs/ai/project-structure.md: Auto-generated file tree map (created by contextuate index).
  • docs/ai/agents/: Specialized "personas" for your AI (e.g., documentation-expert).
  • docs/ai/standards/: Explicit coding standards and behavioral guidelines.
  • docs/ai/quickrefs/: Condensed documentation optimized for AI token limits.
  • docs/ai/tasks/: A workflow for managing multi-session AI tasks.
  • docs/ai/skills/: Slash commands that activate special behaviors (e.g., /orchestrate).

How LLMs Use Contextuate

  1. Discovery: The AI reads docs/ai/.contextuate/contextuate.md first. This file maps the project and links to all other resources.
  2. Specialization: If acting as a specific agent, it reads docs/ai/agents/<name>.md to load specific capabilities and rules.
  3. Execution: The AI follows the linked standards in docs/ai/standards/ and uses docs/ai/quickrefs/ for technical lookups.
  4. Memory: If working on a long-running task, it tracks state in docs/ai/tasks/<task-name>/ to maintain context across sessions.

When using the contextuate run command, this context loading is automated based on the agent definition.

Repository Structure

This repository contains the source for the Contextuate framework.

  • docs/ai/.contextuate/: The core framework files distributed to users.
    • agents/: Base agent definitions.
    • templates/: Templates for new projects.
    • tools/: AI tool guides.

Usage

Once installed, you customize the framework for your project:

  1. Edit docs/ai/context.md with your project details (Identity, Tech Stack).
    • Note: docs/ai/.contextuate/contextuate.md is the framework entry point and typically shouldn't be edited.
  2. Create custom agents in docs/ai/agents/ (using the Agent Creator tool).
  3. Document coding standards in docs/ai/standards/.
  4. Generate quickrefs in docs/ai/quickrefs/.

CLI Usage

Global Options

contextuate --help     # Display all available commands
contextuate --version  # Display the installed version
contextuate -V         # Short form for version

Command Reference

Command Description
init Initialize Contextuate in a project
install Install templates (agents, standards)
run Execute an agent
create-agent Create a new agent definition
index Generate a project file tree
add-context Interactively add files to context
remove Clean up framework files
monitor Real-time Claude Code session monitoring

contextuate init

Initialize Contextuate in the current project.

# Interactive mode - prompts for platforms and agents
contextuate init

# Non-interactive - specify platforms directly
contextuate init claude cursor copilot
contextuate init all  # Install all platforms

# With agents
contextuate init claude --agents archon base
contextuate init claude --agents all

# Force overwrite existing files
contextuate init claude --force

Options:

  • -f, --force - Overwrite existing files
  • -a, --agents <names...> - Install specific agents (e.g., "base archon" or "all")

Available Platforms: agents, antigravity, claude, cline, cursor, gemini, copilot, windsurf

contextuate install

Install templates from the global Contextuate repository. Supports both flag-style and subcommand-style usage.

# Interactive mode
contextuate install

# List available templates
contextuate install --list

# Install all templates
contextuate install --all

# Flag style - install specific items
contextuate install --agents archon base canvas
contextuate install --standards php javascript
contextuate install --tools quickref
contextuate install --skills orchestrate

# Subcommand style
contextuate install agents archon base
contextuate install agents --all
contextuate install standards php javascript python
contextuate install standards --all
contextuate install tools --all
contextuate install skills --all

# Force overwrite
contextuate install agents --all --force

Options:

  • -a, --agents <names...> - Install specific agents
  • -s, --standards <names...> - Install language standards
  • -t, --tools <names...> - Install tools
  • -k, --skills <names...> - Install skills (slash commands)
  • --all - Install all available templates
  • -l, --list - List available templates
  • -f, --force - Overwrite existing files

Subcommands:

  • install agents [names...] - Install agent templates (also installs skills by default)
  • install standards [names...] - Install language standard templates
  • install tools [names...] - Install tool templates
  • install skills [names...] - Install skill templates (slash commands like /orchestrate)

contextuate run

Execute an agent definition with optional task context.

contextuate run documentation-expert
contextuate run archon --goal "Review the codebase structure"
contextuate run forge --task my-feature
contextuate run nexus --dry-run

Options:

  • --dry-run - Simulate execution without running logic
  • --isolation <mode> - Isolation mode (worktree, none). Default: none
  • --goal <text> - Goal or instructions for the agent
  • --task <name> - Load a task context (scope and latest log)

contextuate create-agent

Create a new agent definition.

# Interactive mode
contextuate create-agent

# With name
contextuate create-agent my-custom-agent
contextuate new-agent my-custom-agent  # Alias

# With description
contextuate create-agent api-expert --description "Expert in REST API design"

Options:

  • -d, --description <text> - Description of the agent

contextuate index

Generate a project structure index for AI context.

contextuate index
contextuate index --depth 3
contextuate index --force

Options:

  • -d, --depth <number> - Maximum depth of the file tree. Default: 5
  • -f, --force - Overwrite existing index

contextuate add-context

Interactively add files to docs/ai/context.md.

contextuate add-context

contextuate remove

Remove unmodified platform jump files.

contextuate remove

contextuate monitor

Real-time monitoring dashboard for Claude Code sessions. Tracks tool usage, events, and session activity.

Architecture

The monitor uses a 3-layer architecture:

  1. Hooks - Claude Code hooks emit events to the daemon
  2. Daemon - Background process that collects and processes events (runs independently)
  3. UI Server - Web dashboard and WebSocket server for real-time updates
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│     Daemon      │────▶│   UI Server     │
│     (Hooks)     │     │   (Background)  │     │   (Dashboard)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Important: The daemon runs independently of the UI server. Starting the monitor will spawn the daemon, but stopping the monitor will NOT stop the daemon (so it can continue collecting events). Use --all to stop both.

Commands

# Initial setup (interactive)
contextuate monitor init
contextuate monitor init --global   # Install hooks at user level (~/.claude/)
contextuate monitor init --project  # Install hooks at project level (.claude/)

# Start the monitor (auto-starts daemon if not running)
contextuate monitor
contextuate monitor start
contextuate monitor start --port 8080       # Custom HTTP port
contextuate monitor start --ws-port 8081    # Custom WebSocket port
contextuate monitor start --no-open         # Don't open browser
contextuate monitor start --foreground      # Run in foreground (blocking)

# Stop the monitor
contextuate monitor stop          # Stop UI server only (daemon keeps running)
contextuate monitor stop --all    # Stop both UI server and daemon

# Check status
contextuate monitor status

# Daemon management (advanced)
contextuate monitor daemon start            # Start daemon only
contextuate monitor daemon start --detach   # Start daemon in background
contextuate monitor daemon stop             # Stop daemon
contextuate monitor daemon status           # Check daemon status
contextuate monitor daemon logs             # View daemon logs
contextuate monitor daemon logs -f          # Follow daemon logs
contextuate monitor daemon logs -n 100      # Show last 100 lines

Configuration

Configuration is stored in ~/.contextuate/monitor/config.json. Run contextuate monitor init for interactive setup, or edit the file directly.

Full Configuration Example
{
  "mode": "local",
  "server": {
    "host": "0.0.0.0",
    "port": 3847,
    "wsPort": 3848
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "password": null,
    "channel": "contextuate:events"
  },
  "persistence": {
    "enabled": true,
    "type": "file",
    "database": {
      "host": "localhost",
      "port": 3306,
      "database": "contextuate",
      "user": "contextuate",
      "password": "secret"
    }
  },
  "socketPath": "/tmp/contextuate-monitor.sock"
}
Configuration Parameters
Parameter Type Default Description
mode "local" | "redis" "local" Communication mode between components
socketPath string "/tmp/contextuate-monitor.sock" Unix socket path (local mode only)

Server Settings (server):

Parameter Type Default Description
host string "0.0.0.0" Host to bind the HTTP server
port number 3847 HTTP port for the dashboard
wsPort number 3848 WebSocket port for real-time updates

Redis Settings (redis) - for distributed/multi-machine setups:

Parameter Type Default Description
host string "localhost" Redis server host
port number 6379 Redis server port
password string | null null Redis password (optional)
channel string "contextuate:events" Redis pub/sub channel name

Persistence Settings (persistence):

Parameter Type Default Description
enabled boolean true Enable session persistence
type "file" | "mysql" | "postgresql" "file" Storage backend
database object - Database connection settings (required for mysql/postgresql)

Database Settings (persistence.database) - for MySQL/PostgreSQL:

Parameter Type Description
host string Database server host
port number Database server port (3306 for MySQL, 5432 for PostgreSQL)
database string Database name
user string Database username
password string Database password

Note: MySQL and PostgreSQL persistence are planned features. Currently only file-based persistence is fully implemented.

Mode Comparison
Feature Local Mode Redis Mode
Setup complexity Simple Requires Redis server
Multi-machine support No Yes
Single machine Recommended Overkill
Event delivery Unix socket Redis pub/sub
Use case Personal development Team/distributed environments

Files and Directories

~/.contextuate/monitor/
├── config.json      # Monitor configuration
├── sessions/        # Persisted session data
├── raw/             # Raw event files from hooks
├── processed/       # Processed event files
├── hooks/           # Hook scripts
├── daemon.pid       # Daemon process ID
├── daemon.log       # Daemon logs
├── server.pid       # UI server process ID
└── server.log       # UI server logs

Documentation

For full documentation, see contextuate.md or browse the docs/ai/.contextuate/ directory.

Changelog

See CHANGELOG.md for version history and release notes.

License

MIT License

Credits

Powered by Esotech. Created by Alexander Conroy (@geilt).

About

Context Generator which includes Standardized Folders and Installer for all AI Platforms.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

4 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages