Roo Activity Logger

日本語版はこちら

TL;DR

• What is it? — This is an MCP server that automatically logs AI coding assistant activities such as command executions and code generation (supports Roo Code, Cline, Claude Code, etc.).
• What does it do? — It saves activity history as JSON files, which you can search and analyze later.
• How do I use it? — Add it to your Claude Code, Cline, or Roo-Code settings to enable automatic activity logging.

Overview

Roo Activity Logger is an MCP (Model Context Protocol) server that automatically records AI coding assistant development activities — including command executions, code generation, file operations, and more. It supports Claude Code, Cline, Roo-Code, and other MCP-compatible AI assistants. All logs are saved in JSON format, making it easy to search, analyze, and restore context at any time.

How activity logging works

flowchart TD
    A[Roo's Action] --> B[Select Activity Type]
    B --> C[Log via log_activity]
    C --> D[Provide Log Info<br>- Summary<br>- Details<br>- Intention<br>- Context]
    D --> E[Specify Save Directory]
    E --> F[Save as JSON file]

How to search logs and restore context when resuming a task

flowchart TD
    G[Resume Task] --> H[Search with search_logs]
    H --> I[Set Search Filters<br>- Type<br>- Date Range<br>- Text]
    I --> J[Retrieve Related Activities<br>- Parent/Child<br>- Sequence<br>- Related IDs]
    J --> K[Restore Context & Resume<br>- Review Past Intentions<br>- Understand Progress]

Sample Log Entry

Here is an example of a file_operation log entry saved as JSON:

{
  "id": "75add15d-8d5b-4e60-b327-fde785050c86",
  "timestamp": "2025-04-10T01:58:02.905Z",
  "type": "file_operation",
  "level": "info",
  "summary": "Inserted mermaid diagram into README.md",
  "details": {
    "file": "README.md",
    "operation": "insert_content",
    "insertedLines": "mermaid code block",
    "position": "after overview section"
  },
  "intention": "To visually explain the flow of saving and retrieving activities",
  "context": "Improving documentation for Roo Activity Logger",
  "parentId": "98280366-1de1-48e0-9914-b3a3409599b4"
}

Each log contains:

• Log level (debug, info, warn, error)
• Summary
• Details (any structured data)
• Intention / Purpose
• Context information
• Parent activity ID (for hierarchy)
• Sequence number (for ordering)
• Related activity IDs (for grouping)

Logs are:

• Saved as date-based JSON files
• Searchable by type, level, date, text, etc.
• Customizable — you can specify different save directories per activity

Features

• Logs various activity types:

  • Command executions (command_execution)
  • Code generation (code_generation)
  • File operations (file_operation)
  • Errors (error_encountered)
  • Decisions (decision_made)
  • Conversations (conversation)

• Each activity log includes:

  • Unique ID
  • Timestamp
  • Activity type
  • Summary, details, intention, context, and optional metadata

Usage (Recommended: via npx)

You can run Roo Activity Logger directly without cloning the repository by using npx.

Add this to your Cline, Roo-Code, or Claude Code configuration:

{
  "mcpServers": {
    "roo-activity-logger": {
      "command": "npx",
      "args": ["-y", "github:annenpolka/roo-logger"],
      "env": {},
      "disabled": false
    }
  }
}

Then, add prompts to your rule files (for Cline/Roo-Code) or CLAUDE.md (for Claude Code) to ensure logging, for example:

## Important

Always log activities using roo-activity-logger according to the logging rules.

## Preparation

Check the current context with `git status`.

Then, use roo-activity-logger's `search_logs` to review existing logs and identify current tasks.

Be sure to perform the logging steps.

## Logging

- Always use roo-activity-logger for all logs
- Include stack traces and execution context
- Record intention and context

---

For Developers: Local Setup

To develop or customize locally, clone the repository and build:

# Clone the repo (replace yourusername with your actual username/org)
git clone https://github.com/annenpolka/roo-logger.git
cd roo-logger

# Install dependencies
npm install

# Build
npm run build

Example configuration to use your local build:

{
  "mcpServers": {
    "roo-activity-logger": {
      "command": "node",
      "args": ["/path/to/your/local/roo-logger/dist/index.js"], // adjust path accordingly
      "env": {},
      "disabled": false
    }
  }
}

Notes

• The specified directory will be created automatically if it does not exist.

---

MCP Tools

log_activity — Record an activity

A tool to record an activity.

Basic example

{
  "type": "command_execution",
  "summary": "Run npm command",
  "intention": "Update project dependencies",
  "context": "Preparing for new feature development",
  "logsDir": "/absolute/path/to/logs/activity"
}

Parameters

Name	Required	Type	Description
type	Yes	string	Activity type (command_execution, code_generation, file_operation, error_encountered, decision_made, conversation)
summary	Yes	string	Short summary of the activity
intention	Yes	string	Purpose or intention
context	Yes	string	Context information
logsDir	Yes	string	Save directory (absolute path only)
level	No	string	Log level (debug, info, warn, error). Default: info
details	No	object	Additional details (any JSON)
parentId	No	string	Parent activity ID
sequence	No	number	Sequence number
relatedIds	No	string[]	Related activity IDs

Detailed example

{
  "type": "file_operation",
  "summary": "Update README file",
  "intention": "Clarify documentation and improve usability",
  "context": "Improvements based on user feedback",
  "level": "info",
  "details": {
    "file": "README.md",
    "operation": "update",
    "changedLines": 15
  },
  "logsDir": "/absolute/path/to/logs/activity",
  "sequence": 3,
  "relatedIds": ["11223344-5566-7788-99aa-bbccddeeff00"]
}

---

get_log_files — List saved log files

Lists saved log files recursively. You can specify the maximum search depth.

Basic example

{
  "logsDir": "/absolute/path/to/logs"
}

Parameters

Name	Required	Type	Description
logsDir	Yes	string	Directory to search (absolute path only)
limit	No	number	Max files to retrieve (default: 10)
offset	No	number	Number of files to skip (default: 0)
logFilePrefix	No	string	Log file prefix (default: "roo-activity-")
logFileExtension	No	string	Log file extension (default: ".json")
maxDepth	No	number	Max directory depth (default: 3)

---

search_logs — Search saved logs

Searches saved logs with various filters.

Basic example

{
  "logsDir": "/absolute/path/to/logs"
}

{
  "logsDir": "/absolute/path/to/logs",
  "type": "command_execution"
}

Parameters

Name	Required	Type	Description
logsDir	Yes	string	Log directory (absolute path only)
logFilePrefix	No	string	Log file prefix (default: "roo-activity-")
logFileExtension	No	string	Log file extension (default: ".json")
type	No	string	Filter by activity type (command_execution, code_generation, file_operation, error_encountered, decision_made, conversation)
level	No	string	Filter by log level (debug, info, warn, error)
startDate	No	string	Start date (YYYY-MM-DD)
endDate	No	string	End date (YYYY-MM-DD)
searchText	No	string	Search text in summary or details
limit	No	number	Max logs to retrieve (default: 50)
offset	No	number	Number of logs to skip (default: 0)
parentId	No	string	Filter by parent activity ID
sequenceFrom	No	number	Sequence number lower bound
sequenceTo	No	number	Sequence number upper bound
relatedId	No	string	Filter by related activity ID
relatedIds	No	string[]	Filter by any of related activity IDs

---

License

MIT