Erasmus: Intelligent Context Management System

Overview

Erasmus is an advanced context management library AI driven IDE software development. It provides intelligent context tracking, protocol-driven workflows, multi-IDE support, and automated documentation. It is designed to power AI coding assistants and streamline project management.

Version 0.4.0 - Improved error handling, path management, and CLI interface with a focus on stability and maintainability.

Getting Started

Install

Navigate to the root of the project and run the following command:

curl -sSL https://raw.githubusercontent.com/bakobiibizo/erasmus/refs/heads/main/releases/erasmus/0.5.0/erasmus_v0.5.0.sh -o erasmus.sh && bash erasmus.sh

That should install erasmus into that folder and make it available in your PATH. You can now run erasmus --version to verify the installation.

Usage

Basic Setup

# Initialize Erasmus in your project
erasmus setup

# Start monitoring context files
erasmus watch

The setup command initializes Erasmus in your project and guides you through:

• IDE selection (Windsurf, Cursor, Codex, Claude Code, or Warp Terminal)
• Creating initial context files
• Selecting a protocol for your workflow

The watch command monitors your .ctx.* files and updates your IDE's rules file automatically, injecting context into your AI assistant's window.

Workflow Best Practices

1. Project Initialization

   • Run erasmus setup to initialize your project
   • Define clear requirements in the architecture document
   • Select an appropriate protocol for your current task

2. Development Cycle

   • Let the AI agent manage context files
   • Keep requests focused on the current protocol's scope
   • Use Test-Driven Development (TDD) for better results
   • Regularly remind the agent to update context files

3. Context Management

   • Review the .ctx.architecture.md file for accuracy
   • Use erasmus context store to save context snapshots
   • Switch contexts with erasmus context select for different project components

Effective Prompting Examples

Initial Project Setup:

Help me develop a book search application with features X, Y, and Z using [STACK]. 
Please create an architecture document I can review.

Project Planning:

The architecture looks good. Let's create progress and tasks files to schedule development.

Development:

Let's proceed with development. Please use TDD and keep the context files updated.

Context

The context is a collection of files that define the state of your project. It is stored in the ./erasmus/context directory under the name of the first line with a single "#" in the .ctx.architecture.md file.

.ctx.architecture.md - This file is the main architecture file for your project. It should contain a high level overview of your project and the stack you are using. It should also contain requirements, user stories, and criteria. .ctx.progress.md - This file is the main progress file for your project. It should contain mid level components or multi step processes that define the state of your project. .ctx.tasks.md - This file is the main tasks file for your project. It should contain granular tasks broken out from the progress file.

You dont need to edit these files directly. The agent in your IDE will be aware of the existence of these files and will automatically have their context injected into their context windows. You do have to prompt them to update them from time to time as the model becomes too focused on development to update them.

If your project is very large sometimes you may want to have seperate contexts for different components of your project. You can create a new context by running erasmus context create and entering the context name.

You can swap contexts by running erasmus context select and then selecting the context you want to switch to.

To store your context use erasmus context store and it will detect the first line with a single "#" in the .ctx.architecture.md file and use that as the context name storing the .ctx files in root to ./erasmus/context/<context name>

Protocols

The protocols define the workflow for your agent. You should have a protocol for any major workflow that your agent is running. Erasmus comes with some predefined protocols for your use such as development and debugging. Particularly the orchestration protocol should be used when creating new protocols and modifying multiple contexts. You can find the predefined protocols and edit them in ./erasmus/templates/protocols.

To create a custom protocol use erasmus protocol create and enter the protocol name. You can then edit the protocol in ./erasmus/protocol/<protocol name>.

Protocols are static work flow definitions so they dont need to be stored as a context file does.

Cross-Platform Testing with GitHub Actions

Erasmus includes GitHub Actions workflows to test your container across multiple platforms (Linux, macOS, and Windows).

Running Tests

1. Push your changes to GitHub
2. Go to the "Actions" tab in your repository
3. Select the "Docker Test Matrix" workflow
4. Click "Run workflow" to manually trigger the tests

Test Results

• Tests run on: Ubuntu, macOS, and Windows
• Each platform builds and runs the Docker container
• Test results are available in the workflow logs
• If tests fail, logs are available as artifacts for debugging

Key Features

• Path Management: Centralized, cross-platform path handling for Windsurf, Cursor, Codex, Claude, and Warp
• Environment Configuration: Type-safe, dynamic environment variable management
• Context Management: Save/load .ctx.architecture.md, .ctx.progress.md, .ctx.tasks.md
• Protocol Handling: Define, store, and execute development protocols (developer, documentation, dependency, etc.)
• File Monitoring: Real-time tracking of context files and automatic rules file updates with ASCII sanitization
• MCP Integration: Enhanced CLI and protocol support for GitHub/MCP workflows with improved error handling
• Robust Error Handling: Standardized error patterns and recovery mechanisms throughout the codebase
• Safe File Operations: Consistent path handling and file operations with proper error management

Architecture and Workflow

Core Components

• Path Management (erasmus/utils/paths.py and erasmus/utils/path_resolver.py)
• Error Handling (erasmus/utils/error_handler.py)
• Environment Management (erasmus/environment.py)
• Context Management (erasmus/context.py)
• Protocol Handler (erasmus/protocol.py)
• File Monitor Service (erasmus/file_monitor.py)
• CLI (erasmus/cli/main.py and subcommands)
• MCP Integration (erasmus/mcp/ modules)
• Templates and Protocols (.erasmus/templates/)

Directory Structure

erasmus/
├── erasmus/
│   ├── cli/               # CLI commands and utilities
│   ├── context.py         # Context management
│   ├── environment.py     # Environment variable handling
│   ├── file_monitor.py    # File monitoring service
│   ├── protocol.py        # Protocol handling
│   ├── mcp/               # MCP system integration
│   │   ├── client.py      # MCP client implementation
│   │   ├── models.py      # Data models for MCP
│   │   ├── registry.py    # MCP registry management
│   │   └── servers.py     # MCP server management
│   ├── utils/             # Utility modules
│   │   ├── error_handler.py  # Centralized error handling
│   │   ├── path_resolver.py  # Path resolution utilities
│   │   ├── paths.py          # Path management
│   │   └── rich_console.py   # Console output utilities
│   └── ...
├── .erasmus/
│   ├── templates/         # System templates
│   ├── protocols/         # Protocol definitions
│   ├── context/           # Named context directories
│   ├── mcp/               # MCP configuration
│   └── logs/              # Log files
├── .ctx.architecture.md   # Project architecture context
├── .ctx.progress.md       # Project progress tracking
├── .ctx.tasks.md          # Detailed task breakdown
├── README.md
└── ...

Workflow

1. Define project architecture in .ctx.architecture.md
2. Track progress in .ctx.progress.md
3. Break down tasks in .ctx.tasks.md
4. Use erasmus watch to monitor and sync context
5. Use protocols to drive development, documentation, and releases
6. Leverage the enhanced MCP integration for GitHub workflows

Context File Structure

• .ctx.architecture.md: Project blueprint (high-level design, stack, user stories, criteria)
• .ctx.progress.md: Development tracking (component progress, blockers, dependencies)
• .ctx.tasks.md: Granular task management (detailed breakdown, status, assignment)

Installation

Quick Install

curl -sSL https://raw.githubusercontent.com/bakobiibizo/erasmus/refs/heads/main/releases/erasmus/0.4.1/erasmus_v0.4.1.sh | bash

Command Line Usage

Erasmus provides a powerful CLI for managing development contexts, protocols, and project setup. Here are a few key examples:

# List all contexts
erasmus context list

# Create a new protocol
erasmus protocol create my-protocol

# Setup a new project interactively
erasmus setup

# Watch for .ctx file changes
erasmus watch

# Show current status
erasmus status

For a full list of commands and detailed usage, see docs/CLI_COMMANDS.md.

What Does Erasmus Do?

Erasmus sits in the background of your development environment and:

1. Tracks Project Context - Maintains a complete view of your codebase structure, decisions, and progress
2. Powers IDE Context Injection - Feeds rich context to AI code assistants in compatible IDEs
3. Monitors Development Files - Watches for changes in key files like architecture docs and progress tracking
4. Creates Essential Documentation - Automatically generates and updates project documentation
5. Handles Errors Gracefully - Provides consistent error handling and recovery mechanisms
6. Ensures ASCII Compatibility - Sanitizes rules files for cross-platform compatibility

Protocols

• Developer: Implements code, tracks tasks, ensures code quality
• Documentation: Maintains docs, tracks doc tasks
• Dependency: Manages dependencies, tracks updates
• Testing, CI/CD, Security, Style, Product Owner, etc.

Completion Criteria

• All core components implemented and tested
• Protocols in use for all major workflows
• Documentation and context files up-to-date
• Automated rules file updates working in all supported IDEs
• Standardized error handling throughout the codebase
• Safe file operations with proper error management

Contributing

See CONTRIBUTING.md for guidelines.

Recent Improvements

Version 0.5.0

• Enhanced Error Handling: Standardized error patterns and recovery mechanisms throughout the codebase
• Improved Path Management: Safe file operations with consistent error handling
• CLI Interface Optimization: Better user feedback and command structure
• MCP System Enhancements: Optimized StdioClient with better subprocess management and error recovery
• File Monitor Refactoring: Split complex functions into smaller, more maintainable pieces
• ASCII Sanitization: Ensure rules files maintain ASCII-only content for cross-platform compatibility

License

MIT

Making MCP Calls to Servers

Erasmus supports making JSON-RPC calls to MCP servers (such as the GitHub MCP server) via both the CLI and programmatically. The system has been enhanced with improved error handling and connection reliability. Below are the key details and sharp edges to be aware of when constructing these calls:

1. JSON-RPC Request Structure

• Every session must begin with an initialize request.
• Tool calls use the tools/call method.
• The params object for tools/call must include:
  • name: The tool's name (e.g., list_branches, get_user). This is NOT the JSON-RPC method name, but the tool identifier.
  • arguments: A dictionary of arguments required by the tool. All tool-specific parameters must be nested inside this arguments object.

Example JSON-RPC tool call:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_branches",
    "arguments": {
      "owner": "bakobi",
      "repo": "hexamerous"
    }
  },
  "id": 2
}

Sharp Edges:

• The name field is required and must match the tool's identifier exactly.
• All tool arguments must be inside the arguments dictionary. Passing them at the top level will result in errors.
• The method is always tools/call for tool invocations, not the tool name itself.
• You must send an initialize request first in the same session.
• The server will respond with one JSON object per line for each request (e.g., one for initialize, one for the tool call).

2. CLI Usage

You can invoke MCP tools via the Erasmus CLI:

erasmus mcp servers github list_branches --owner bakobi --repo hexamerous

The CLI handles the JSON-RPC structure for you, but you must provide all required arguments as CLI options. The CLI will pretty-print the server's response, including any nested JSON content.

3. Programmatic Usage (Python)

To make calls programmatically, use the enhanced StdioClient class with improved error handling:

from erasmus.mcp.client import StdioClient
from erasmus.utils.error_handler import safe_operation, McpError

def call_github_api():
    client = StdioClient()
    try:
        # The client now has improved error handling and connection reliability
        stdout, stderr = client.communicate(
            server_name="github",
            method="tools/call",
            params={
                "name": "list_branches",
                "arguments": {
                    "owner": "bakobi",
                    "repo": "hexamerous"
                }
            }
        )
        return stdout
    except McpError as e:
        # Standardized error handling for MCP-related errors
        print(f"MCP error: {e}")
        return None
    finally:
        # Ensure proper cleanup of resources
        client.disconnect_all()

# Use the safe_operation utility for consistent error handling
result = safe_operation(call_github_api, "Failed to call GitHub API")
if result:
    print(result)

Note:

• Always send both initialize and tools/call requests in the same session (the client does this for you).
• Parse each line of the response as a separate JSON object.
• The tool response is usually the last JSON object returned.
• Use the new error handling utilities for consistent error management.

4. Common Pitfalls

• Missing arguments nesting: All tool parameters must be inside the arguments dict.
• Incorrect name: The name must match the tool's identifier, not the method.
• Forgetting initialize: The server expects an initialize request before any tool calls.
• Parsing responses: The server returns one JSON object per line; parse each line separately.

Refer to the CLI help (erasmus mcp servers github --help) for available tools and their required arguments.