Clogcast

Zero-config log sharing for AI coding assistants - makes any application's logs visible to Claude Code and Cursor.

What is Clogcast?

When using AI coding tools like Claude Code or Cursor, developers have traditionally needed to copy and paste terminal output to share error messages and logs with the AI assistant. This manual process interrupts the development flow and prevents the AI from autonomously detecting and fixing issues.

Clogcast solves this by transparently capturing your application's output and making it available to AI assistants through the Model Context Protocol (MCP). Simply prefix any command with clogcast and your AI assistant can read the logs directly, enabling it to understand what's happening and self-correct errors without manual intervention.

# Before (manually copy/paste logs to AI)
npm run dev

# After (AI reads logs directly)
clogcast npm run dev

Features

• Zero Configuration: Just prefix your command with clogcast
• Universal: Works with any command or application
• Transparent: Your terminal experience remains unchanged
• Cross-Platform: Works on macOS, Linux, and Windows
• Shared Buffer: All AI assistant instances can access the same logs

Installation

Global Installation (Recommended)

npm install -g clogcast

Add to Claude Code

Add the following to your .mcp.json file:

{
  "mcpServers": {
    "clogcast": {
      "command": "node",
      "args": ["/path/to/global/node_modules/clogcast/dist/mcp-server.js"]
    }
  }
}

To find the path to your global installation:

npm list -g clogcast

Usage

Important Note

Claude Code users: You must start Claude Code first before running any clogcast commands. Claude Code loads MCP servers on startup.

Cursor users: MCP servers load automatically when the IDE starts, so you can use clogcast immediately.

Basic Usage

Simply prefix any command with clogcast:

# Node.js applications
clogcast npm run dev
clogcast npm test

# Python applications
clogcast python app.py
clogcast pytest

Using with Claude Code

Once your application is running with clogcast, you can ask Claude Code to examine the logs. For example:

• "Can you check the logs for any errors?"
• "What's causing the database connection to fail?"
• "Show me the recent API requests in the logs"

Claude Code can automatically filter logs by:

• Error output (stderr)
• Time range (e.g., last 5 minutes)
• Search terms (e.g., "error", "warning", "failed")
• Number of recent entries

Handling Large Log Volumes

⚠️ Context Limit Warning: Large log retrievals can exceed Claude Code's ~25,000 token context limit, causing session failures.

Best Practices for Large Logs

1. Always use filtering parameters:

   # Good: Specific, limited query
   "Show me errors from the last 5 minutes (limit 100)"
      
   # Risky: Could return thousands of entries
   "Show me all logs"

2. Use subagents for comprehensive analysis: When you need to analyze extensive logs (>200 entries), Claude Code will automatically delegate to a subagent to prevent context overflow:

   Task({
     description: "Analyze authentication errors",
     prompt: "Use clogcast to find all 'auth failed' errors in the last 30 minutes. 
              Summarize patterns and provide counts, not raw logs."
   })

3. Recommended parameter values:

   • limit: 50-200 entries (prevents overflow)
   • since_minutes: 5-10 minutes (focused time range)
   • search: Specific terms like error names or component identifiers
   • level: "stderr" for error-only analysis

4. Progressive refinement: Start with broad searches using strict limits, then narrow based on findings:

   • First: "Show last 50 errors"
   • Then: "Show 'ConnectionError' from last 10 minutes"
   • Finally: "Show full stack trace for that specific error"

How It Works

1. Process Wrapping: Clogcast spawns your command as a child process
2. Output Capture: Stdout and stderr are captured in real-time
3. Terminal Pass-through: All output is displayed in your terminal as normal
4. HTTP Ingestion: Logs are sent to a local HTTP server (port 24281)
5. MCP Integration: Claude Code accesses logs via MCP tools
6. Ring Buffer: Last 10,000 log entries are kept in memory

Architecture

Terminal → clogcast → Your App
            ↓
         HTTP POST
            ↓
      MCP Server ← Claude Code
         ↓  ↑
      HTTP API

Multi-Instance Support

Clogcast supports multiple MCP server instances sharing the same log buffer:

• The first instance starts the HTTP server on port 24281
• Additional instances detect the running server and share the log buffer
• All Claude Code windows can access the same logs
• Automatic fallback to local buffer if HTTP server is unavailable

MCP Tools

get_logs

Retrieve logs from the buffer with optional filtering:

• limit: Maximum number of entries to return
• level: Filter by 'stdout' or 'stderr'
• search: Case-insensitive text search
• since_minutes: Only logs from the last N minutes

get_log_stats

Get statistics about the current log buffer:

• Total number of entries
• Count of stdout vs stderr entries
• Buffer capacity
• Timestamp of oldest and newest entries

clear_logs

Clear all logs from the buffer.

Advanced Features

Signal Handling

Clogcast properly forwards all signals to the wrapped application:

• SIGTERM, SIGINT, SIGQUIT, SIGHUP are forwarded
• Exit codes are preserved

Error Resilience

• Network errors are silently ignored
• MCP server crashes don't affect your application
• Fire-and-forget design ensures zero performance impact

Cross-Platform Support

• Uses cross-spawn for reliable process spawning
• Handles platform-specific shell differences
• Works with spaces and special characters in commands

HTTP API

Clogcast exposes HTTP endpoints for programmatic access to logs:

GET /api/logs

Query logs with optional filters:

curl "http://localhost:24281/api/logs?limit=10&level=stderr&search=error&since_minutes=5"

Query parameters:

• limit: Maximum number of entries to return
• level: Filter by 'stdout' or 'stderr'
• search: Case-insensitive text search
• since_minutes: Only logs from the last N minutes

GET /api/stats

Get log buffer statistics:

curl "http://localhost:24281/api/stats"

DELETE /api/logs

Clear all logs:

curl -X DELETE "http://localhost:24281/api/logs"

Troubleshooting

Logs not appearing in Claude

1. Ensure clogcast is in your .mcp.json
2. Restart Claude Code after configuration changes
3. Check that the wrapped command is actually producing output

Port 24281 already in use

This usually means another clogcast instance is running, which is fine! All instances share the same log buffer.

Command not found

Make sure to install clogcast globally with -g flag, or add the local installation to your PATH.

License

MIT © Papercut Labs