cleat 0.1.0__tar.gz

cleat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      # fish exercises the native-OSC-133 path; bash/zsh are already present.
+      - name: Install fish (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y fish
+      - name: Install fish (macOS)
+        if: runner.os == 'macOS'
+        run: brew install fish
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v

cleat-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+# Publish to PyPI when a version tag is pushed (e.g. v0.1.0).
+# Uses PyPI Trusted Publishing (OIDC) — no API tokens stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment: pypi          # configure this name in the PyPI trusted publisher
+    permissions:
+      id-token: write          # required for OIDC trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cleat-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# venvs
+.venv/
+venv/
+*-venv/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

cleat-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 sidyellur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project vendors bash-preexec (src/cleat/vendor/bash-preexec.sh), which is
+licensed separately under the MIT License, Copyright (c) 2017 Ryan Caloras and
+contributors. See src/cleat/vendor/bash-preexec.LICENSE.md.

cleat-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: cleat
+Version: 0.1.0
+Summary: A headless terminal layer: a persistent PTY + OSC 133 structure source, exposed to AI agents over MCP.
+Project-URL: Homepage, https://github.com/sidyellur/cleat
+Project-URL: Issues, https://github.com/sidyellur/cleat/issues
+Author-email: sidyellur <20009719+sidyellur@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 sidyellur
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        ---
+        
+        This project vendors bash-preexec (src/cleat/vendor/bash-preexec.sh), which is
+        licensed separately under the MIT License, Copyright (c) 2017 Ryan Caloras and
+        contributors. See src/cleat/vendor/bash-preexec.LICENSE.md.
+License-File: LICENSE
+Keywords: agent,claude,claude-code,mcp,osc133,pty,shell-integration,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0
+Requires-Dist: ptyprocess>=0.7
+Requires-Dist: pyte>=0.8
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cleat
+
+[![CI](https://github.com/sidyellur/cleat/actions/workflows/ci.yml/badge.svg)](https://github.com/sidyellur/cleat/actions/workflows/ci.yml)
+
+**A headless terminal layer for AI agents.** `cleat` runs a *persistent* shell
+session behind a PTY, parses its byte stream for [OSC 133](https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md)
+shell-integration marks, and exposes it to an agent over [MCP](https://modelcontextprotocol.io)
+as **structured results** — `stdout`, real `exit_code`, files touched — instead
+of raw escape-code soup.
+
+It is *not* a terminal emulator and *not* a modification to your terminal. It's
+a separate process that runs inside whatever terminal you already use, and it
+stays terminal-agnostic.
+
+## Why
+
+When an agent drives a terminal, it normally sees a continuous byte river:
+prompt redraws, echoed keystrokes, color codes, and output, with no marker for
+where one command's output ends or whether it succeeded. Worse, when you scrape
+a PTY, **the exit code isn't in the stream at all** — the shell knows `$?` but
+never prints it.
+
+`cleat` injects OSC 133 marks into the shells it spawns and parses them back
+out, so the agent gets:
+
+```json
+{ "stdout": "...", "exit_code": 0, "completed": true }
+```
+
+…and the session is **persistent**: `cd`, `export`, activated venvs, and `ssh`
+sessions all carry across calls — something a fresh `subprocess` per command
+cannot do.
+
+## Install
+
+Requires Python ≥3.10 on a POSIX system (Linux/macOS). With [uv](https://docs.astral.sh/uv/) installed, register it with Claude Code:
+
+```sh
+claude mcp add cleat -- uvx --from git+https://github.com/sidyellur/cleat cleat
+```
+
+Or add it to a project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cleat": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/sidyellur/cleat", "cleat"]
+    }
+  }
+}
+```
+
+For local development:
+
+```sh
+git clone https://github.com/sidyellur/cleat && cd cleat
+python -m venv .venv && . .venv/bin/activate
+pip install -e .
+cleat            # runs the MCP server over stdio
+```
+
+## Tools
+
+| Tool | Returns | Use for |
+|------|---------|---------|
+| `run_command(command, timeout)` | `{stdout, exit_code, completed}` (+ `files_changed` if watching) | normal commands — full, exact stdout |
+| `read_output(timeout)` | `{output, exit_code, completed}` | watching a long-running / streaming command |
+| `read_screen()` | `{screen, cursor}` | inspecting a full-screen TUI (vim, top, less) |
+| `send_keys(keys, enter)` | `{screen, cursor, exit_code, completed}` | driving a REPL / TUI / prompt (control chars pass through: ``=Ctrl-C) |
+| `resize(cols, rows)` | `{cols, rows}` | laying out a TUI for a given size |
+| `watch_files(path)` | `{watch_root}` | enable per-command `files_changed` under `path` |
+
+`completed: false` means the program is still running or waiting for input (e.g.
+a REPL) — drive it with `send_keys` and poll with `read_output`.
+
+## How it works
+
+```
+agent ─(MCP)─ server.py ─ engine.py (persistent PTY, ptyprocess)
+                            ├─ structure.py  → OSC 133 marks → {stdout, exit_code}
+                            └─ pyte screen    → rendered view for REPLs/TUIs
+```
+
+The engine injects OSC 133 per shell without touching your real config: zsh via
+a temp `$ZDOTDIR`, bash via `--rcfile` + vendored [bash-preexec](https://github.com/rcaloras/bash-preexec),
+and fish ≥4 via its native shell integration (older fish is unsupported).
+
+## Caveats
+
+- **POSIX only.** Uses `pty`/`termios`; no Windows.
+- **It gives the agent a real shell.** Commands run with your user's privileges
+  in a persistent session. Run it only where you'd let an agent run shell
+  commands.
+- **`files_changed` detects writes, not reads** (create/modify/delete under the
+  watched root). Read-tracking needs privileged syscall tracing.
+- **bash:** a command whose *first token* is a subshell `(...)` or brace group
+  `{ ...; }` emits no start mark; its exit code is recovered but stdout for that
+  one command is not captured.
+- **Full-screen TUIs:** use `read_screen` (the rendered grid), not `run_command`.
+- **Shells:** zsh and bash are fully supported. fish requires **≥4** (native OSC
+  133) and is supported for command execution; interactive REPL/TUI *driving* is
+  verified on zsh/bash.
+
+## License
+
+MIT (see [LICENSE](LICENSE)). Vendors bash-preexec, also MIT.

cleat-0.1.0/README.md

@@ -0,0 +1,108 @@
+# cleat
+
+[![CI](https://github.com/sidyellur/cleat/actions/workflows/ci.yml/badge.svg)](https://github.com/sidyellur/cleat/actions/workflows/ci.yml)
+
+**A headless terminal layer for AI agents.** `cleat` runs a *persistent* shell
+session behind a PTY, parses its byte stream for [OSC 133](https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md)
+shell-integration marks, and exposes it to an agent over [MCP](https://modelcontextprotocol.io)
+as **structured results** — `stdout`, real `exit_code`, files touched — instead
+of raw escape-code soup.
+
+It is *not* a terminal emulator and *not* a modification to your terminal. It's
+a separate process that runs inside whatever terminal you already use, and it
+stays terminal-agnostic.
+
+## Why
+
+When an agent drives a terminal, it normally sees a continuous byte river:
+prompt redraws, echoed keystrokes, color codes, and output, with no marker for
+where one command's output ends or whether it succeeded. Worse, when you scrape
+a PTY, **the exit code isn't in the stream at all** — the shell knows `$?` but
+never prints it.
+
+`cleat` injects OSC 133 marks into the shells it spawns and parses them back
+out, so the agent gets:
+
+```json
+{ "stdout": "...", "exit_code": 0, "completed": true }
+```
+
+…and the session is **persistent**: `cd`, `export`, activated venvs, and `ssh`
+sessions all carry across calls — something a fresh `subprocess` per command
+cannot do.
+
+## Install
+
+Requires Python ≥3.10 on a POSIX system (Linux/macOS). With [uv](https://docs.astral.sh/uv/) installed, register it with Claude Code:
+
+```sh
+claude mcp add cleat -- uvx --from git+https://github.com/sidyellur/cleat cleat
+```
+
+Or add it to a project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cleat": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/sidyellur/cleat", "cleat"]
+    }
+  }
+}
+```
+
+For local development:
+
+```sh
+git clone https://github.com/sidyellur/cleat && cd cleat
+python -m venv .venv && . .venv/bin/activate
+pip install -e .
+cleat            # runs the MCP server over stdio
+```
+
+## Tools
+
+| Tool | Returns | Use for |
+|------|---------|---------|
+| `run_command(command, timeout)` | `{stdout, exit_code, completed}` (+ `files_changed` if watching) | normal commands — full, exact stdout |
+| `read_output(timeout)` | `{output, exit_code, completed}` | watching a long-running / streaming command |
+| `read_screen()` | `{screen, cursor}` | inspecting a full-screen TUI (vim, top, less) |
+| `send_keys(keys, enter)` | `{screen, cursor, exit_code, completed}` | driving a REPL / TUI / prompt (control chars pass through: ``=Ctrl-C) |
+| `resize(cols, rows)` | `{cols, rows}` | laying out a TUI for a given size |
+| `watch_files(path)` | `{watch_root}` | enable per-command `files_changed` under `path` |
+
+`completed: false` means the program is still running or waiting for input (e.g.
+a REPL) — drive it with `send_keys` and poll with `read_output`.
+
+## How it works
+
+```
+agent ─(MCP)─ server.py ─ engine.py (persistent PTY, ptyprocess)
+                            ├─ structure.py  → OSC 133 marks → {stdout, exit_code}
+                            └─ pyte screen    → rendered view for REPLs/TUIs
+```
+
+The engine injects OSC 133 per shell without touching your real config: zsh via
+a temp `$ZDOTDIR`, bash via `--rcfile` + vendored [bash-preexec](https://github.com/rcaloras/bash-preexec),
+and fish ≥4 via its native shell integration (older fish is unsupported).
+
+## Caveats
+
+- **POSIX only.** Uses `pty`/`termios`; no Windows.
+- **It gives the agent a real shell.** Commands run with your user's privileges
+  in a persistent session. Run it only where you'd let an agent run shell
+  commands.
+- **`files_changed` detects writes, not reads** (create/modify/delete under the
+  watched root). Read-tracking needs privileged syscall tracing.
+- **bash:** a command whose *first token* is a subshell `(...)` or brace group
+  `{ ...; }` emits no start mark; its exit code is recovered but stdout for that
+  one command is not captured.
+- **Full-screen TUIs:** use `read_screen` (the rendered grid), not `run_command`.
+- **Shells:** zsh and bash are fully supported. fish requires **≥4** (native OSC
+  133) and is supported for command execution; interactive REPL/TUI *driving* is
+  verified on zsh/bash.
+
+## License
+
+MIT (see [LICENSE](LICENSE)). Vendors bash-preexec, also MIT.

cleat-0.1.0/client_test.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Smoke test: drive the cleat MCP server over the REAL stdio transport.
+
+    python client_test.py    # requires `pip install -e .`
+"""
+
+import asyncio
+import sys
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+def _text(result):
+    return "".join(c.text for c in result.content if getattr(c, "type", "") == "text")
+
+
+async def main():
+    params = StdioServerParameters(command=sys.executable, args=["-m", "cleat.server"])
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            tools = await session.list_tools()
+            print("tools:", [t.name for t in tools.tools])
+
+            r = await session.call_tool(
+                "run_command", {"command": "echo live over stdio; uname -s"})
+            print("\nrun #1:\n" + _text(r))
+
+            # Persistence across SEPARATE MCP tool calls - the subprocess-can't-do-this bit.
+            await session.call_tool("run_command", {"command": "export FOO=persisted"})
+            await session.call_tool("run_command", {"command": "cd /tmp"})
+            r2 = await session.call_tool("run_command", {"command": "echo $FOO; pwd"})
+            print("\nrun #2 (after export+cd in earlier calls):\n" + _text(r2))
+
+            r3 = await session.call_tool("run_command", {"command": "false"})
+            print("\nrun #3 (failure):\n" + _text(r3))
+
+            # Interactive: start a REPL (won't 'complete'), compute, exit.
+            r4 = await session.call_tool("run_command", {"command": "python3", "timeout": 8})
+            print("\nrun #4 (repl start, completed=False expected):\n" + _text(r4)[-80:])
+            r5 = await session.call_tool("send_keys", {"keys": "print(6*7)", "enter": True})
+            print("\nrun #5 (send_keys -> 42 expected):\n" + _text(r5))
+            r6 = await session.call_tool("send_keys", {"keys": "exit()", "enter": True})
+            print("\nrun #6 (repl exit, completed=True expected):\n" + _text(r6))
+
+            # Full-screen TUI over MCP: open vim, SEE it via read_screen, quit it.
+            await session.call_tool("run_command", {"command": "vim -u NONE -N", "timeout": 4})
+            r7 = await session.call_tool("read_screen", {})
+            print("\nrun #7 (read_screen of vim, '~' rows expected):\n" + _text(r7)[:200])
+            r8 = await session.call_tool("send_keys", {"keys": ":q!", "enter": True})
+            print("\nrun #8 (vim quit, completed=True expected):\n" + _text(r8)[-120:])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cleat-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cleat"
+version = "0.1.0"
+description = "A headless terminal layer: a persistent PTY + OSC 133 structure source, exposed to AI agents over MCP."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "sidyellur", email = "20009719+sidyellur@users.noreply.github.com" }]
+keywords = ["mcp", "terminal", "pty", "osc133", "shell-integration", "agent", "claude", "claude-code"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Topic :: Terminals",
+]
+dependencies = [
+    "ptyprocess>=0.7",
+    "pyte>=0.8",
+    "mcp>=1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build"]
+
+[project.scripts]
+cleat = "cleat.server:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/sidyellur/cleat"
+Issues = "https://github.com/sidyellur/cleat/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cleat"]
+# The vendored bash-preexec.sh (+ its license) under src/cleat/vendor/ ships
+# automatically (hatchling includes all non-VCS-ignored files in the package);
+# the bash injection rcfile references it by absolute path at runtime.

cleat-0.1.0/src/cleat/__init__.py

@@ -0,0 +1,8 @@
+"""cleat - a headless terminal layer for AI agents.
+
+A persistent PTY shell session whose byte stream is parsed for OSC 133 marks and
+exposed to an agent over MCP as structured results (stdout, exit code, files
+touched), plus a virtual screen for interactive programs and TUIs.
+"""
+
+__version__ = "0.1.0"