teemux 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2026, Gajus Kuizinas (https://gajus.com/)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Gajus Kuizinas (https://gajus.com/) nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL GAJUS KUIZINAS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,167 @@
+# teemux
+
+Aggregate logs from multiple processes in a single view – in browser or terminal.
+
+## 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.
+
+## Install
+
+```bash
+npm install -g teemux
+```
+
+## Usage
+
+```bash
+teemux --name api -- node api.js
+teemux --name worker -- node worker.js
+teemux -- redis-server  # name defaults to "redis-server"
+```
+
+The first process starts a local server on port 8336. Others connect automatically.
+
+### Options
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--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 |
+
+All options can also be set via environment variables with `TEEMUX_` prefix:
+
+```bash
+TEEMUX_PORT=9000 teemux -- node app.js
+```
+
+## Viewing Logs
+
+### Browser
+
+Open http://127.0.0.1:8336/ to view aggregated logs with:
+
+- Color-coded process names
+- Auto-scroll (sticks to bottom like a terminal)
+- Scroll up to pause, scroll back down to resume
+
+### Terminal / curl
+
+```bash
+curl http://127.0.0.1:8336/
+```
+
+Plain text stream of all logs.
+
+### AGENTS.md
+
+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:
+
+````md
+## Viewing Logs
+
+All process logs are aggregated at http://127.0.0.1:8336/
+
+```bash
+# View all recent logs
+curl http://127.0.0.1:8336/
+
+# View logs from a specific process
+curl "http://127.0.0.1:8336/?include=[api]"
+
+# View only errors (using wildcard for case variations)
+curl "http://127.0.0.1:8336/?include=*error*,*Error*,*ERROR*"
+
+# View logs from api OR worker
+curl "http://127.0.0.1:8336/?include=[api],[worker]"
+
+# Exclude noisy logs (using wildcard)
+curl "http://127.0.0.1:8336/?exclude=health*,DEBUG"
+```
+````
+
+### Filtering Logs
+
+Use query parameters to filter logs:
+
+| Parameter | Logic | Description |
+|-----------|-------|-------------|
+| `include` | OR | Show lines matching **any** of the patterns |
+| `exclude` | OR | Hide lines matching **any** of the patterns |
+
+Patterns support `*` as a wildcard (matches any characters):
+
+```bash
+# Show only logs from the api process
+curl "http://127.0.0.1:8336/?include=[api]"
+
+# Show only error logs (using wildcard)
+curl "http://127.0.0.1:8336/?include=*error*"
+
+# Show logs from api OR worker
+curl "http://127.0.0.1:8336/?include=[api],[worker]"
+
+# Hide healthcheck and ping logs
+curl "http://127.0.0.1:8336/?exclude=health*,ping"
+
+# Show GET requests to /api endpoints
+curl "http://127.0.0.1:8336/?include=*GET*/api*"
+
+# Show api logs but exclude verbose debug output
+curl "http://127.0.0.1:8336/?include=[api]&exclude=DEBUG,TRACE"
+
+# In browser
+open "http://127.0.0.1:8336/?include=[api]&exclude=health*"
+```
+
+Filters apply to both buffered logs and new incoming logs in real-time.
+
+## Output Example
+
+**Terminal (where teemux runs):**
+```
+● started (pid 12345)
+Server listening on :3000
+Processing jobs...
+GET /health 200
+○ exited (code 0)
+```
+
+**Browser / curl (aggregated with prefixes):**
+```
+[api] ● started (pid 12345)
+[api] Server listening on :3000
+[worker] Processing jobs...
+[api] GET /health 200
+[worker] ○ exited (code 0)
+```
+
+## FAQ
+
+### Docker output appears corrupted with strange spacing
+
+When running Docker with the `-t` flag, output may appear corrupted:
+
+```
+Initializing database...
+                        The files belonging to this database system...
+```
+
+**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.
+
+**Solution:** Remove the `-t` flag when running through teemux:
+
+```bash
+# ❌ Don't use -t
+teemux --name db -- docker run --rm -it my-database
+
+# ✅ Use -i only (or neither flag)
+teemux --name db -- docker run --rm -i my-database
+teemux --name db -- docker run --rm my-database
+```
+
+The flags:
+- `-i` = keep stdin open (for interactive input) ✅
+- `-t` = allocate pseudo-TTY (adds terminal formatting) ❌

package/dist/teemux.d.ts

@@ -0,0 +1 @@
+export { };