teemux 1.8.0 → 1.9.0

package/README.md

@@ -1,11 +1,29 @@
-# teemux
+<p align="center">
+  <img src="assets/teemux.png" alt="teemux" width="120" />
+</p>
 
-Aggregate logs from multiple processes in a single view – in browser or terminal.
+<h1 align="center">teemux</h1>
+
+<p align="center">
+  <strong>Aggregate logs from multiple processes in a single view</strong>
+</p>
+
+<p align="center">
+  View in browser or terminal • Filter with patterns • Stream to AI agents via MCP
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/teemux"><img src="https://img.shields.io/npm/v/teemux.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/teemux"><img src="https://img.shields.io/npm/dm/teemux.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/gajus/teemux/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/teemux.svg" alt="license" /></a>
+</p>
+
+---
 
 ## Motivation
 
 * Needed a simple way to browse logs aggregated across multiple processes.
-* Needed a simple way to [give agents a unified view of all the logs](#agentsmd).
+* Needed a simple way to give agents a unified view of all the logs
 
 ## Install
 
@@ -29,7 +47,8 @@ The first process starts a local server on port 8336. Others connect automatical
 |--------|-------|---------|-------------|
 | `--name` | `-n` | command name | Identifier for this process in logs |
 | `--port` | `-p` | 8336 | Port for the log aggregation server |
-| `--tail` | `-t` | 1000 | Number of log lines to keep in buffer |
+| `--buffer` | `-b` | 10000 | Number of log lines to keep in server buffer |
+| `--force-leader` | `-f` | false | Force this process to become the leader, replacing any existing leader |
 
 All options can also be set via environment variables with `TEEMUX_` prefix:
 
@@ -55,32 +74,62 @@ curl http://127.0.0.1:8336/
 
 Plain text stream of all logs.
 
-### AGENTS.md
+### MCP Server for AI Agents
 
-If you want your coding agent to see the logs, simply add instructions to AGENTS.md to view the logs by running `curl http://127.0.0.1:8336/`. Example:
+teemux includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI agents to programmatically access logs in your development environment. This makes it easy for coding assistants like Claude, Cursor, or other AI tools to inspect application logs, search for errors, and understand what's happening in your running processes.
 
-````md
-## Viewing Logs
+The MCP server runs on the same port as the HTTP server at `/mcp` and provides these tools:
 
-All process logs are aggregated at http://127.0.0.1:8336/
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `get_logs` | Get recent logs from buffer | `limit?`, `include?`, `exclude?` |
+| `search_logs` | Search logs with patterns | `limit?`, `include?`, `exclude?` |
+| `clear_logs` | Clear the log buffer | none |
+| `get_process_names` | List all process names that have logged | none |
 
-```bash
-# View all recent logs
-curl http://127.0.0.1:8336/
+#### Configuring your AI agent
 
-# View logs from a specific process
-curl "http://127.0.0.1:8336/?include=api"
+Add teemux as an MCP server in your AI tool's configuration. For Claude Code, add to your MCP settings:
 
-# View only errors (using wildcard for case variations)
-curl "http://127.0.0.1:8336/?include=*error*,*Error*,*ERROR*"
+```json
+{
+  "mcpServers": {
+    "teemux": {
+      "url": "http://127.0.0.1:8336/mcp"
+    }
+  }
+}
+```
 
-# View logs from api OR worker
-curl "http://127.0.0.1:8336/?include=api,worker"
+Once configured, your AI agent can:
+- **Inspect logs** when debugging issues ("What errors are in the logs?")
+- **Search for specific events** ("Find all database connection errors")
+- **Monitor processes** ("What processes are currently running?")
+- **Clear logs** to start fresh when testing
+
+#### Example MCP usage
 
-# Exclude noisy logs (using wildcard)
-curl "http://127.0.0.1:8336/?exclude=health*,DEBUG"
+```bash
+# Initialize session
+curl -X POST http://127.0.0.1:8336/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'
+
+# List available tools (use session ID from response above)
+curl -X POST http://127.0.0.1:8336/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "mcp-session-id: <session-id>" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
+
+# Get recent logs
+curl -X POST http://127.0.0.1:8336/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "mcp-session-id: <session-id>" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_logs","arguments":{"limit":50}},"id":3}'
 ```
-````
 
 ### Filtering Logs
 
@@ -181,3 +230,16 @@ teemux --name db -- docker run --rm my-database
 The flags:
 - `-i` = keep stdin open (for interactive input) ✅
 - `-t` = allocate pseudo-TTY (adds terminal formatting) ❌
+
+## Developing
+
+```bash
+# Install dependencies
+npm install
+
+# Build and watch for changes
+npm run dev
+
+# In another terminal, run with fake logs
+node dist/teemux.js -- node scripts/fake-logs.js
+```