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

Project Initialization
- Run erasmus setup to initialize your project
- Define clear requirements in the architecture document
- Select an appropriate protocol for your current task
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
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

Push your changes to GitHub
Go to the "Actions" tab in your repository
Select the "Docker Test Matrix" workflow
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

Define project architecture in .ctx.architecture.md
Track progress in .ctx.progress.md
Break down tasks in .ctx.tasks.md
Use erasmus watch to monitor and sync context
Use protocols to drive development, documentation, and releases
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:

Tracks Project Context - Maintains a complete view of your codebase structure, decisions, and progress
Powers IDE Context Injection - Feeds rich context to AI code assistants in compatible IDEs
Monitors Development Files - Watches for changes in key files like architecture docs and progress tracking
Creates Essential Documentation - Automatically generates and updates

Erasmus

Install / Use

README