echograph 0.5.18

Context Engineering CLI for Claude Code

EchoGraph CLI

Context Engineering CLI for Claude Code - scaffold, validate, and maintain your AI-assisted development workflow.

Installation

Recommended: Using uv (all platforms)

# Install uv first (if you don't have it)
# Windows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iex

# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Then install echograph
uv tool install echograph

# With AI-assisted merge support (optional)
uv tool install echograph[ai]

# Upgrade to latest version
uv tool upgrade echograph

Alternative: Using pip

pip install echograph

# With AI-assisted merge support (optional)
pip install echograph[ai]

Note: On Windows, you may need to add the Scripts folder to your PATH. The installer will show the path (typically C:\Users\<username>\AppData\Roaming\Python\Python3XX\Scripts).

One-time usage (no install)

uvx echograph init

Quick Start

# Navigate to your project
cd /path/to/your-project

# Initialize Context Engineering
echograph init

# Check your setup
echograph doctor

# Validate context files
echograph validate

Commands

echograph init

Scaffold Context Engineering templates for your project.

# Interactive mode (asks questions)
echograph init

# Minimal setup (core files only)
echograph init --minimal

# Full setup (all templates and commands)
echograph init --full

# Merge missing sections into existing CLAUDE.md
echograph init --merge

# Overwrite existing files
echograph init --force

# Preview without creating files
echograph init --dry-run

# AI-assisted smart merge (requires echograph[ai])
echograph init --smart-merge

# Initialize a specific directory
echograph init /path/to/project

Created files (minimal):

• CLAUDE.md - Project conventions (at project root)
• .claude/PLANNING.md - Architecture and goals
• .claude/TASK.md - Task tracking

Additional files (full):

• .claude/commands/ - Slash commands
• .claude/skills/ - Custom skills
• .claude/tasks/ - Feature task templates
• PRPs/ - Product Requirement Prompts structure

Using --merge with existing projects:

If your project already has a CLAUDE.md, use --merge to add missing sections from the template without overwriting your existing content:

echograph init --merge

This will:

• Keep all your existing sections intact
• Add any sections from the template that you're missing (e.g., Response Optimization, Security Rules)
• Match sections case-insensitively (ignoring emojis)

Using --smart-merge for AI-assisted merging:

When you have existing files with customizations, use --smart-merge to let Claude intelligently merge your changes with new template features:

echograph init --smart-merge

This requires the [ai] extra (uv tool install echograph[ai]) and an Anthropic API key. On first use, you'll be prompted to enter your API key, which can be saved for future use.

The smart merge:

• Preserves your custom project names, paths, and sections
• Adds new template features you don't have
• Updates generic boilerplate with improved versions
• Shows a diff preview before applying changes

You can also choose smart merge interactively when handling conflicts (option 5).

echograph update

Update templates while preserving your customizations using three-way merge.

# Update templates
echograph update

# Preview changes without modifying files
echograph update --dry-run

How it works:

1. Compares your current files with the original template version
2. Merges in new template changes
3. Preserves your customizations
4. Marks conflicts for manual resolution (if any)

echograph validate

Check context files for completeness and valid references.

# Validate current directory
echograph validate

# Validate specific directory
echograph validate /path/to/project

# Treat warnings as errors
echograph validate --strict

Checks performed:

• Required files exist (CLAUDE.md at root, PLANNING.md and TASK.md in .claude/)
• @ imports reference existing files
• CLAUDE.md has Project Context section
• TASK.md has required sections (In Progress, Pending, Completed)

echograph doctor

Diagnose your Claude Code setup.

echograph doctor

Checks performed:

• Claude Code CLI is installed (claude command available)
• .claude/ directory structure is correct
• MCP configuration is valid (if present)
• Project is a git repository
• Template version is current

Configuration

The CLI auto-detects project configuration:

• Project name: From git remote or folder name
• Tech stack: From pyproject.toml, package.json, Cargo.toml, etc.
• Test framework: From pytest.ini, jest.config.js, etc.

Templates are customized based on detected configuration.

Coming Soon

These commands show a "coming soon" message:

• echograph search - Semantic code search
• echograph sync - Sync external sources (GitHub, Azure DevOps)
• echograph decision - Track architectural decisions

Development

# Clone the repository
git clone https://github.com/echograph/echograph
cd echograph

# Install dependencies
uv sync --all-packages

# Run tests
uv run pytest --cov

# Run linters
uv run ruff check packages/cli/
uv run mypy packages/cli/src/

License

MIT