Skip to content
Back to search

teemux

Zero-config log multiplexer with built-in MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gajus--teemux/badge.svg)](/listings/gajus--teemux)

HTML

<a href="/listings/gajus--teemux"><img src="/api/listings/gajus--teemux/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g teemux

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 263 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/teemux.png" alt="teemux" width="120" />
  3. </p>
  4. <h1 align="center">teemux</h1>
  5. <p align="center">
  6. <strong>Aggregate logs from multiple processes in a single view</strong>
  7. </p>
  8. <p align="center">
  9. View in browser or terminal • Filter with patterns • Stream to AI agents via MCP
  10. </p>
  11. <p align="center">
  12. <a href="https://www.npmjs.com/package/teemux"><img src="https://img.shields.io/npm/v/teemux.svg" alt="npm version" /></a>
  13. <a href="https://www.npmjs.com/package/teemux"><img src="https://img.shields.io/npm/dm/teemux.svg" alt="npm downloads" /></a>
  14. <a href="https://github.com/gajus/teemux/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/teemux.svg" alt="license" /></a>
  15. </p>
  16. <p align="center">
  17. <img src="./preview.gif" alt="teemux demo" width="600" />
  18. </p>
  19. <p align="center">
  20. <a href="https://teemux.com/">View a demo of Teemux in action</a>
  21. </p>
  22. ---
  23. ## Demo
  24. ```bash
  25. npx teemux -- curl -N https://teemux.com/random-logs
  26. ```
  27. ## Motivation
  28. * Needed a simple way to browse logs aggregated across multiple processes.
  29. * Needed a simple way to give agents a unified view of all the logs
  30. ## Install
  31. ```bash
  32. npm install -g teemux
  33. ```
  34. ## Usage
  35. ```bash
  36. teemux --name api -- node api.js
  37. teemux --name worker -- node worker.js
  38. teemux -- redis-server # name defaults to "redis-server"
  39. ```
  40. The first process starts a local server on port 8336. Others connect automatically.
  41. ### Options
  42. | Option | Alias | Default | Description |
  43. |--------|-------|---------|-------------|
  44. | `--name` | `-n` | command name | Identifier for this process in logs |
  45. | `--port` | `-p` | 8336 | Port for the log aggregation server |
  46. | `--buffer` | `-b` | 10000 | Number of log lines to keep in server buffer |
  47. | `--force-leader` | `-f` | false | Force this process to become the leader, replacing any existing leader |
  48. All options can also be set via environment variables with `TEEMUX_` prefix:
  49. ```bash
  50. TEEMUX_PORT=9000 teemux -- node app.js
  51. ```
  52. ## Viewing Logs
  53. ### Browser
  54. Open http://127.0.0.1:8336/ to view aggregated logs with:
  55. - Color-coded process names
  56. - Auto-scroll (sticks to bottom like a terminal)
  57. - Scroll up to pause, scroll back down to resume
  58. ### Terminal / curl
  59. ```bash
  60. curl http://127.0.0.1:8336/
  61. ```
  62. Plain text stream of all logs.
  63. ### MCP Server for AI Agents
  64. 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.
  65. The MCP server runs on the same port as the HTTP server at `/mcp` and provides these tools:
  66. | Tool | Description | Parameters |
  67. |------|-------------|------------|
  68. | `get_logs` | Get recent logs from buffer | `limit?`, `include?`, `exclude?` |
  69. | `search_logs` | Search logs with patterns | `limit?`, `include?`, `exclude?` |
  70. | `clear_logs` | Clear the log buffer | none |
  71. | `get_process_names` | List all process names that have logged | none |
  72. #### Configuring your AI agent
  73. Add teemux as an MCP server in your AI tool's configuration. For Claude Code, add to your MCP settings:
  74. ```json
  75. {
  76. "mcpServers": {
  77. "teemux": {
  78. "command": "npx",
  79. "args": [
  80. "mcp-remote",
  81. "http://127.0.0.1:8336/mcp"
  82. ]
  83. }
  84. }
  85. }
  86. ```
  87. Once configured, your AI agent can:
  88. - **Inspect logs** when debugging issues ("What errors are in the logs?")
  89. - **Search for specific events** ("Find all database connection errors")
  90. - **Monitor processes** ("What processes are currently running?")
  91. - **Clear logs** to start fresh when testing
  92. #### Example MCP usage
  93. ```bash
  94. # Initialize session
  95. curl -X POST http://127.0.0.1:8336/mcp \
  96. -H "Content-Type: application/json" \
  97. -H "Accept: application/json, text/event-stream" \
  98. -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'
  99. # List available tools (use session ID from response above)
  100. curl -X POST http://127.0.0.1:8336/mcp \
  101. -H "Content-Type: application/json" \
  102. -H "Accept: application/json, text/event-stream" \
  103. -H "mcp-session-id: <session-id>" \
  104. -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
  105. # Get recent logs
  106. curl -X POST http://127.0.0.1:8336/mcp \
  107. -H "Content-Type: application/json" \
  108. -H "Accept: application/json, text/event-stream" \
  109. -H "mcp-session-id: <session-id>" \
  110. -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_logs","arguments":{"limit":50}},"id":3}'
  111. ```
  112. ### Filtering Logs
  113. Use query parameters to filter logs:
  114. | Parameter | Logic | Description |
  115. |-----------|-------|-------------|
  116. | `include` | OR | Show lines matching **any** of the patterns |
  117. | `exclude` | OR | Hide lines matching **any** of the patterns |
  118. Patterns support `*` as a wildcard (matches any characters):
  119. ```bash
  120. # Show only logs from the api process
  121. curl "http://127.0.0.1:8336/?include=api"
  122. # Show only error logs (using wildcard)
  123. curl "http://127.0.0.1:8336/?include=*error*"
  124. # Show logs from api OR worker
  125. curl "http://127.0.0.1:8336/?include=api,worker"
  126. # Hide healthcheck and ping logs
  127. curl "http://127.0.0.1:8336/?exclude=health*,ping"
  128. # Show GET requests to /api endpoints
  129. curl "http://127.0.0.1:8336/?include=*GET*/api*"
  130. # Show api logs but exclude verbose debug output
  131. curl "http://127.0.0.1:8336/?include=api&exclude=DEBUG,TRACE"
  132. # In browser
  133. open "http://127.0.0.1:8336/?include=api&exclude=health*"
  134. ```
  135. Filters apply to both buffered logs and new incoming logs in real-time.
  136. ## Output Example
  137. **Terminal (where teemux runs):**
  138. ```
  139. ● started (pid 12345)
  140. Server listening on :3000
  141. Processing jobs...
  142. GET /health 200
  143. ○ exited (code 0)
  144. ```
  145. **Browser / curl (aggregated with prefixes):**
  146. ```
  147. [api] ● started (pid 12345)
  148. [api] Server listening on :3000
  149. [worker] Processing jobs...
  150. [api] GET /health 200
  151. [worker] ○ exited (code 0)
  152. ```
  153. ## FAQ
  154. ### What's the origin of the name?
  155. The name combines **tee** (the Unix command that duplicates output) and **mux** (multiplexer) – it multiplexes multiple log streams into one.
  156. ### How does teemux work?
  157. teemux uses automatic leader discovery to coordinate log aggregation across multiple processes:
  158. 1. **Leader Discovery**: When the first teemux process starts, it attempts to bind to the configured port (default 8336). If successful, it becomes the **leader** and starts the log aggregation server.
  159. 2. **Client Registration**: When subsequent teemux processes start, they detect the port is already in use, verify a server is responding, and automatically become **clients** that forward their logs to the leader.
  160. 3. **Leader Election**: If the leader process exits, clients detect this through periodic health checks (every 2 seconds). When a client detects the leader is gone, it attempts to become the new leader. Random jitter prevents multiple clients from racing to claim leadership simultaneously.
  161. This design requires no configuration – just run multiple `teemux` commands and they automatically coordinate.
  162. ### Docker output appears corrupted with strange spacing
  163. When running Docker with the `-t` flag, output may appear corrupted:
  164. ```
  165. Initializing database...
  166. The files belonging to this database system...
  167. ```
  168. **Cause:** The `-t` flag allocates a pseudo-TTY, which adds terminal control sequences (cursor positioning, colors, etc.) to the output. These sequences are meant for interactive terminal use, not for piping.
  169. **Solution:** Remove the `-t` flag when running through teemux:
  170. ```bash
  171. # ❌ Don't use -t
  172. teemux --name db -- docker run --rm -it my-database
  173. # ✅ Use -i only (or neither flag)
  174. teemux --name db -- docker run --rm -i my-database
  175. teemux --name db -- docker run --rm my-database
  176. ```
  177. The flags:
  178. - `-i` = keep stdin open (for interactive input) ✅
  179. - `-t` = allocate pseudo-TTY (adds terminal formatting) ❌
  180. ## Developing
  181. ```bash
  182. # Install dependencies
  183. npm install
  184. # Build and watch for changes
  185. npm run dev
  186. # In another terminal, run with fake logs
  187. node dist/teemux.js -- node scripts/fake-logs.js
  188. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.