Chronos Protocol

🚀 Chronos Protocol

Chronos Protocol revolutionizes AI development workflows. It eliminates temporal blindness in automated systems, offering complete traceability and session continuity. With enterprise - grade time tracking, intelligent scheduling, and comprehensive development analytics, it empowers AI agents to maintain context across sessions.

🚀 Quick Start

Chronos Protocol is a game - changer for AI development. It fills the critical gaps in AI development workflows with its advanced time intelligence and persistent memory systems, tailored for automated coding environments.

✨ Features

Core Capabilities

Chronos Protocol addresses key issues in AI development workflows through sophisticated time intelligence and persistent memory systems, specifically designed for automated coding environments.

System Time First Approach

Chronos Protocol changes how automated systems handle time by prioritizing your computer's local system time as the intelligent default. There's no more timezone confusion. Just use "system" or "local" and get instant, contextual time awareness that adapts to your environment.

Core Time Intelligence

get_current_time - Temporal Awareness Made Simple

Chronos Protocol prioritizes your computer's local system time as the intelligent default. Most AI IDEs already embed system time in their prompts, but Chronos Protocol provides explicit, structured temporal context that works across all MCP clients.

Get standardized timestamps with system time context:

• System Time Priority: Uses your local system time as the intelligent default.
• Cross - Timezone Collaboration: Shows local time alongside team timezone for global projects.
• Temporal Context: AI agents always know "when" they're operating for better decision - making.

convert_time - Smart Timezone Translation

Eliminate timezone calculation errors with intelligent conversion:

• Meeting Scheduling: Convert times between global timezones.
• Release Planning: Coordinate deployments across regions.
• Time Difference Analysis: Calculate timezone offsets with DST handling.

Activity Intelligence System

start_activity_log - Intelligent Context Initialization

Start sophisticated activity monitoring with unique Activity IDs and rich metadata for agentic development workflows:

• Autonomous Session Management: Track coding sessions, debugging processes, and feature implementations with persistent context.
• Intelligent Task Analysis: Monitor and learn from task completion patterns to optimize future planning.
• Context Preservation: Maintain precise records for cross - session continuity and seamless task resumption.

end_activity_log - Success Documentation & Analytics

Complete activities with automatic duration calculation and rich outcome data for performance intelligence:

• Self - Performance Analysis: Analyze actual vs. estimated completion times for better future planning accuracy.
• Autonomous Documentation: Document accomplishments and lessons learned for persistent knowledge retention.
• Adaptive Performance: Build historical intelligence on development velocity and success patterns.

get_elapsed_time - Real - Time Progress Monitoring

Monitor ongoing activities without interrupting execution flow:

• Long - Running Task Management: Check progress on extended debugging or complex implementations.
• Intelligent Time Boxing: Monitor and optimize work sessions for maximum efficiency.
• Context Awareness: Track duration of different phases in problem - solving processes.

get_activity_logs - Historical Intelligence & Pattern Analysis

Query and analyze development patterns with sophisticated filtering:

• Autonomous Pattern Recognition: Generate performance reports and identify optimization opportunities.
• Self - Learning Analytics: Identify which task types require more resources and adapt approach accordingly.
• Cross - Project Learning: Leverage experience from different projects to improve overall effectiveness.

update_activity_log - Intelligent Activity Management

Modify completed activities with updated insights and corrections:

• Autonomous Learning: Add insights discovered after task completion for future reference.
• Self - Correction: Fix timing errors or update task descriptions based on new information.
• Continuous Documentation: Update results and learnings as projects evolve and new context emerges.

Intelligent Reminder System

create_time_reminder - Contextual Task Scheduling

Set smart reminders linked to your development workflow:

• Code Review Follow - ups: Never forget to check on pending pull requests.
• Dependency Updates: Schedule regular checks for outdated packages and security patches.
• Release Checkpoints: Set reminders for deployment, testing, and rollback windows.

check_time_reminders - Proactive Awareness System

Stay ahead of important tasks with intelligent reminder detection:

• Upcoming Deadlines: Get advance warning of approaching project milestones.
• Maintenance Windows: Be reminded of scheduled system maintenance or deployments.
• Team Coordination: Never miss collaborative sessions or important check - ins.

Problem Statement

Solves Real Problems

• Eliminates AI Temporal Blindness: Your AI agents can actively check current time and make time - aware decisions instead of relying solely on embedded system time in the its System Prompt.
• Reduces Context Switching: AI agents can track time without interrupting your flow.
• Cross - Project Continuity: Start tracking in Project A, finish in Project B - everything stays connected.
• Developer - Centric Design: Built specifically for agentic coding workflows, not generic time tracking.

Architecture

Flexible Storage Architecture

Chronos Protocol supports dual storage modes to fit your development workflow:

Centralized Mode (Traditional)

• Single database for all projects.
• Cross - project analytics and historical intelligence.
• Perfect for: Teams wanting unified time tracking across all work.
• AI Framework Integration: Persistent memory works across all projects.

Per - Project Mode (Dynamic)

• Automatic project detection with zero configuration.
• Isolated storage per project ({project - root}/chronos - data/time_server_data.json).
• Perfect for: Individual developers who prefer project - specific tracking.
• Zero Setup: Just use --storage - mode per - project and it works everywhere.

Context Engineering Framework Integration

Chronos Protocol's activity logging system provides persistent memory for AI frameworks like [Claude Task Master](https://github.com/eyaltoledano/claude - task - master), [Agent OS](https://github.com/buildermethods/agent - os), and [BMAD Method](https://github.com/bmad - code - org/BMAD - METHOD), enabling enhanced task tracking, centralized activity logging, and historical analysis with persistent Activity IDs across agent operations.

Integration Guide: For AI coding agents, refer to the sample prompt template in AGENTS.md which provides Cursor Rules that can be integrated with your existing workflow rules. This template demonstrates the complete activity logging protocol with customizable task list filename patterns.

Persistent Memory Benefits

• Cross - Session Continuity: Tasks started in one session can be tracked and completed in another.
• Framework - Agnostic Storage: JSON database works with any AI framework that can append Activity IDs.
• Rich Context Preservation: Full activity metadata including duration, outcomes, and custom tags.
• Historical Intelligence: AI frameworks can query past activities for pattern recognition and optimization.

📦 Installation

Prerequisites

• Python: 3.10 or higher
• MCP Support: AI client with Model Context Protocol support

Installation Steps

# 1. Clone the repository
git clone https://github.com/n0zer0d4y/chronos - protocol.git
cd chronos - protocol

# 2. Install dependencies
pip install -r requirements.txt

# 3. Install in editable mode (required for MCP)
pip install -e .

# 4. Verify installation
python -m chronos_protocol --help

After installation, configure Chronos Protocol in your MCP client using the appropriate configuration schema in the Configuration section.

💻 Usage Examples

Basic Usage

Get Current Time with Context

# Get current time in your system's timezone
get_current_time(timezone="system")
# Returns: Current time with full timezone context

Smart Timezone Conversion

# Convert meeting time across timezones
convert_time(
  source_timezone="America/New_York",
  time="15:00",
  target_timezone="Europe/London"
)
# Returns: Converted time with timezone difference

Advanced Usage

Complete Development Session Tracking

# 1. Start activity logging
activity_id = start_activity_log(
    activityType="debugging",
    task_scope="feature - implementation",
    description="Fix authentication module login flow"
)

# 2. AI agent works on the task...
# Monitor progress with get_elapsed_time(activity_id)

# 3. Complete with results
end_activity_log(
    activity_id,
    result="Authentication module completed successfully"
)

Intelligent Task Analysis

# Get activity history for pattern analysis
activities = get_activity_logs(
    activityType="debugging",
    task_scope="feature - implementation"
)

# AI learns from patterns and timing
for activity in activities:
    analyze_completion_time(activity)
    identify_successful_patterns(activity)

Cross - Session Continuity

# Check for ongoing activities
ongoing = get_activity_logs(status="ongoing")
if ongoing:
    # Resume where you left off
    continue_activity(ongoing[0]["activityId"])

# Learning from history
debug_sessions = get_activity_logs(
    activityType="debugging",
    start_date="2024 - 01 - 01"
)

AI Framework Integration Example

# Example: AI Framework Integration
activity_id = start_activity_log(
    activityType="framework_task",
    task_scope="feature - implementation",
    description="AI agent implementing authentication module",
    tags=["ai - agent", "claude - task - master"]
)

# Your framework stores the activity_id with task data
# Later: end_activity_log(activity_id, result="Authentication module completed")

This creates an intelligent feedback loop where AI frameworks learn from historical task performance and timing patterns!

📚 Documentation

API

Time Intelligence Functions

get_current_time(timezone)

Get standardized timestamps with system time context.

Parameters:

• timezone (string): Target timezone. Use "system" or "local" for user's local time, or IANA names like "America/New_York", "Europe/London", "UTC"

Returns: Current time with full timezone context and metadata

convert_time(source_timezone, time, target_timezone)

Convert time between timezones with intelligent handling of DST.

Parameters:

• source_timezone (string): Source timezone
• time (string): Time in 24 - hour format (HH:MM)
• target_timezone (string): Target timezone

Returns: Converted time with timezone difference information

Activity Intelligence Functions

start_activity_log(activityType, task_scope, description, tags?)

Initialize activity monitoring with unique Activity ID and rich metadata.

Parameters:

• activityType (string): Type of activity (e.g., 'debugging', 'feature - implementation')
• task_scope (string): Scope of the task from predefined options
• description (string): Detailed description of the activity
• tags (array, optional): Array of strings for categorizing the activity

Returns: Unique Activity ID for tracking

end_activity_log(activityId, result?, notes?)

Complete activity with automatic duration calculation and rich outcome data.

Parameters:

• activityId (string): Unique identifier of the activity to end
• result (string, optional): Result or outcome of the activity
• notes (string, optional): Additional notes about the activity

Returns: Completed activity with duration and timestamps

get_elapsed_time(activityId)

Monitor ongoing activities without interrupting execution flow.

Parameters:

• activityId (string): Unique identifier of the activity

Returns: Elapsed time information for the specified activity

get_activity_logs(filters?)

Query and analyze development patterns with sophisticated filtering.

Parameters:

• filters (object, optional): Filtering options including:
  • activityType (string): Filter by activity type
  • task_scope (string): Filter by task scope
  • startDate (string): Filter by start date (ISO 8601 format)
  • endDate (string): Filter by end date (ISO 8601 format)
  • limit (integer): Maximum number of logs to return

Returns: Array of activity logs matching the criteria

update_activity_log(activityId, updates)

Modify completed activities with updated insights and corrections.

Parameters:

• activityId (string): Unique identifier of the activity to update
• updates (object): Object containing fields to update

Returns: Updated activity log

Reminder System Functions

create_time_reminder(reminderTime, message, relatedTaskId?)

Create time - based reminder using system time for scheduling.

Parameters:

• reminderTime (string): Time for the reminder (ISO 8601 format with timezone)
• message (string): Reminder message
• relatedTaskId (string, optional): ID of related task or activity

Returns: Created reminder with unique identifier

check_time_reminders(upcomingMinutes?)

Check for due or upcoming time reminders.

Parameters:

• upcomingMinutes (integer, optional): Check for reminders due within this many minutes (default: 60)

Returns: Array of due and upcoming reminders

Configuration

Chronos Protocol supports two storage modes:

ID Format Options

Important: Type Parameter Warning

⚠️ Important Note

DO NOT add "type": "stdio" to your MCP configuration.

Why this causes failures:

• Chronos Protocol is hardcoded to use stdio transport.
• When clients add "type": "stdio", it can interfere with variable resolution.
• Variable substitution happens before type validation.
• Results in invalid paths like C:\Program Files\VSCode\${workspaceFolder}.

Correct approach:

• Let Chronos Protocol handle transport selection automatically.
• Only specify "type" if your MCP client requires it AND you're not using variables.
• Most MCP clients work perfectly without explicit type declaration.

VS Code Extensions and forks

Roo Code Extension

{
  "mcpServers": {
    "chronos - protocol": {
      "command": "python",
      "args": [
        "-m",
        "chronos_protocol",
        "--storage - mode",
        "per - project",
        "--project - root",
        "${workspaceFolder}",
        "--id - format",
        "custom"
      ]
    }
  }
}

VS Code Forks

{
  "mcpServers": {
    "chronos - protocol": {
      "command": "python",
      "args": [
        "-m",
        "chronos_protocol",
        "--storage - mode",
        "per - project",
        "--project - root",
        "${workspaceFolder}",
        "--id - format",
        "custom"
      ]
    }
  }
}

CLI Clients

{
  "chronos - protocol": {
    "command": "python",
    "args": [
      "-m",
      "chronos_protocol",
      "--storage - mode",
      "per - project",
      "--id - format",
      "custom"
    ]
  }
}

Limited Support Clients

Known Limitations:

• Does not support ${workspaceFolder} variable substitution.
• Cannot use per - project storage mode.
• Will fail if --project - root argument is included.
• Limited to centralized storage only.

Working Configuration:

{
  "chronos - protocol": {
    "disabled": false,
    "timeout": 60,
    "command": "python",
    "args": [
      "-m",
      "chronos_protocol",
      "--storage - mode",
      "centralized",
      "--data - dir",
      "/path/to/centralized/chronos - data",
      "--id - format",
      "custom"
    ]
  }
}

Do NOT add:

• --project - root "${workspaceFolder}" (causes failures).
• "type": "stdio" parameter (see Important section above).

🔧 Technical Details

Troubleshooting

Common Issues

"No tools or prompts" Error

Symptoms:

• MCP server appears connected.
• Tools are not available in the client.
• No error messages visible.

Solutions by Client:

• Cursor:
  • Ensure --project - root "${workspaceFolder}" is included.
  • Check that workspace is properly opened.
• Claude Code:
  • Remove --project - root argument (use default detection).
  • Do not add "type": "stdio" parameter.
• Cline/Qoder:
  • Use centralized storage mode.
  • Remove all workspace variables.
  • Set explicit --data - dir path.

Variable Substitution Issues

Problem: ${workspaceFolder} not resolving. Affected Clients: Cline, Qoder, some Claude Code configurations.

Solution:

{
  "chronos - protocol": {
    "command": "python",
    "args": [
      "-m",
      "chronos_protocol",
      "--storage - mode",
      "centralized",
      "--data - dir",
      "/explicit/path/to/chronos - data"
    ]
  }
}

Storage Permission Errors

Error: Cannot create chronos - data directory. Solution:

• Ensure write permissions in project directory.
• For per - project mode, check workspace permissions.
• For centralized mode, verify --data - dir accessibility.

Python Module Not Found

Error: ModuleNotFoundError: No module named 'chronos_protocol'. Solution:

# Ensure editable installation
pip install -e .
# Verify installation
python -m chronos_protocol --help

Client - Specific Issues

• VS Code Extensions:
  • Ensure MCP extension is enabled.
  • Check VS Code version compatibility.
  • Verify workspace is properly opened.
• VS Code Forks:
  • Some forks may have custom MCP implementations.
  • Check fork - specific documentation.
  • Report issues to fork maintainers.
• CLI Clients:
  • Ensure proper JSON formatting.
  • Check file permissions for configuration files.
  • Verify Python environment setup.

Performance Optimization

• Large Activity Logs:
  • Use appropriate ID format for your use case.
  • Consider centralized storage for cross - project analytics.
  • Archive old activities periodically.
• Memory Usage:
  • Per - project mode isolates memory usage.
  • Centralized mode may accumulate data over time.
  • Monitor storage directory sizes.

Getting Help

• Community Support:
  • Check GitHub issues for similar problems.
  • Provide detailed error logs and configuration.
  • Include client version and platform information.
• Debug Information:

# Get detailed server logs
python -m chronos_protocol --verbose

# Check MCP client logs
# (varies by client - check client documentation)

Contributing

Development Setup

# Fork and clone
git clone https://github.com/n0zer0d4y/chronos - protocol.git
cd chronos - protocol

# Set up development environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

# Run tests
pytest tests/

# Run with debug logging
python -m chronos_protocol --debug

Code Standards

• Python: Follow PEP 8 style guidelines.
• Documentation: Use Google - style docstrings.
• Testing: Maintain >90% test coverage.
• Commits: Use conventional commit format.

Testing MCP Clients

When adding support for new MCP clients:

1. Test with both storage modes.
2. Verify all tools work correctly.
3. Check error handling scenarios.
4. Update configuration documentation.
5. Add to compatibility matrix.

Reporting Bugs

Bug Report Template:

• MCP client name and version.
• Configuration used.
• Expected vs actual behavior.
• Error logs (if available).
• Steps to reproduce.

📄 License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/n0zer0d4y/chronos - protocol/blob/master/LICENSE) file for details.

Acknowledgments

• Anthropic for the Model Context Protocol specification.
• MCP Community for client implementations and testing.
• Contributors for their valuable feedback and bug reports.

Ready to transform your AI development workflow? Configure Chronos Protocol in your MCP client and start building with complete traceability and session continuity.