pairmux 1.0.0__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Binary file
@@ -0,0 +1,245 @@
1
+ Metadata-Version: 2.1
2
+ Name: pairmux
3
+ Version: 1.0.0
4
+ Summary: Blocking terminal control for AI agents on macOS, Linux and Windows, with captured logs and live human handoff
5
+ License: MIT
6
+ Classifier: Development Status :: 5 - Production/Stable
7
+ Classifier: Environment :: Console
8
+ Classifier: Intended Audience :: Developers
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: MacOS
11
+ Classifier: Operating System :: Microsoft :: Windows
12
+ Classifier: Operating System :: POSIX :: Linux
13
+ Classifier: Programming Language :: Go
14
+ Classifier: Topic :: Software Development
15
+ Classifier: Topic :: Terminals
16
+ Classifier: Topic :: Utilities
17
+ Project-URL: Homepage, https://pairmux.treeleaves30760.com
18
+ Project-URL: Repository, https://github.com/treeleaves30760/pairmux
19
+ Project-URL: Documentation, https://pairmux-docs.treeleaves30760.com/
20
+ Project-URL: Changelog, https://github.com/treeleaves30760/pairmux/blob/main/ChangeLog.md
21
+ Project-URL: Issues, https://github.com/treeleaves30760/pairmux/issues
22
+ Keywords: ai agents, terminal, pty, conpty, tmux, cli, mcp, developer tools
23
+ Requires-Python: >=3.9
24
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
25
+
26
+ # pairmux
27
+
28
+ **Let AI agents drive interactive terminal programs — and hand off to a human when they can't.**
29
+
30
+ [Homepage](https://pairmux.treeleaves30760.com) ·
31
+ [Documentation](https://pairmux-docs.treeleaves30760.com/) ·
32
+ [CLI reference](https://pairmux-docs.treeleaves30760.com/cli-reference) ·
33
+ [Changelog](https://github.com/treeleaves30760/pairmux/blob/main/ChangeLog.md) ·
34
+ [Source](https://github.com/treeleaves30760/pairmux)
35
+
36
+ pairmux is a small Agent-Computer Interface layer over a terminal multiplexer, with no service for
37
+ you to install or supervise. It runs natively on macOS, Linux and Windows: it uses tmux when tmux is
38
+ installed on macOS or Linux, and otherwise its own built-in multiplexer (a PTY on Unix, ConPTY on
39
+ Windows). Agents get a real terminal with persistent shell state and actionable command outcomes;
40
+ humans keep normal access to the same live terminal — watch, take over, hand back.
41
+
42
+ ## Why pairmux
43
+
44
+ - **A real PTY.** Exec-style agent shell tools run commands without a terminal, so REPLs, `psql`,
45
+ `ssh` password prompts, `docker exec -it`, `git rebase -i`, pagers, and TUIs are impossible
46
+ there. pairmux makes them drivable.
47
+ - **Human handoff on credentials and judgment calls.** A recognized secret prompt never suggests
48
+ an answer; `wait --human --notify`, `attach`, and `note` turn a blocked credential prompt into a
49
+ resumable checkpoint — and the wait ends as soon as the human answers, note or no note.
50
+ - **Persistent shell state.** `source venv/bin/activate`, `export`, and `nvm use` happen once in a
51
+ live shell instead of being re-composed into every command.
52
+ - **Actionable waits and captured history.** `run` blocks until completion, a recognized prompt,
53
+ or timeout (never killing the command); journals retain full output with exit codes, and
54
+ `--json` emits a versioned `pairmux.v1` envelope with ordered next steps.
55
+
56
+ ## Install
57
+
58
+ With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, add a persistent
59
+ `pairmux` command to PATH:
60
+
61
+ ```bash
62
+ uv tool install pairmux
63
+ pairmux version
64
+ pairmux doctor
65
+ ```
66
+
67
+ This ordinary install retains your environment and uv configuration, including index overrides,
68
+ and may reuse cache. Check `command -v pairmux` for an older installation shadowing the new one.
69
+
70
+ ### Update (v0.6.0+)
71
+
72
+ From **v0.6.0** onward, update the currently running, verified persistent uv tool installation
73
+ (including one created by the installer):
74
+
75
+ ```bash
76
+ pairmux update
77
+ ```
78
+
79
+ **v0.5.3 and older have no `update` command.** First use `uv tool install --upgrade pairmux` with
80
+ your normal configuration to obtain v0.6.0+ when available, then use the new command.
81
+
82
+ The updater needs uv installed. It clears all inherited `UV_*` settings, ignores uv configuration,
83
+ and reinstalls from **`https://pypi.org/simple`** with no persistent cache or source builds,
84
+ replacing old exact pins, constraints, indexes, and extras. It selects the latest compatible stable
85
+ wheel, never below the running version's numeric core; recognized alpha/beta/rc builds can advance
86
+ to that core's final or a later stable release, but dev/snapshot builds are refused.
87
+
88
+ A version change returns `updated`; a same-version reinstall returns `refreshed`, not a no-op.
89
+ Failures return `E_UPDATE` with a recovery hint, without a guaranteed rollback. Recover with the
90
+ original manager, or `uv tool install --upgrade pairmux` for uv installs (normal configuration
91
+ applies). It does not update Homebrew, RPM, pipx/pip, manual/development installs, or temporary uvx
92
+ runs, and does not touch tmux. There are no command-specific options, automatic updates, sudo, or
93
+ uv bootstrap/update; global `--json` is supported.
94
+
95
+ ### Optional temporary run with uvx
96
+
97
+ ```bash
98
+ uvx pairmux version
99
+ uvx pairmux doctor
100
+ ```
101
+
102
+ `uvx` remains supported. It uses a temporary tool environment, which uv may cache, or reuses an
103
+ existing uv-managed installation; it does not promise the latest version or a fresh download every
104
+ time. Temporary runs cannot use `pairmux update`.
105
+
106
+ ### Alternative installer
107
+
108
+ The [inspectable installer](https://pairmux.treeleaves30760.com/install.sh) persistently installs
109
+ pairmux with uv from the public PyPI index:
110
+
111
+ ```bash
112
+ curl -fsSL https://pairmux.treeleaves30760.com/install.sh | bash
113
+ ```
114
+
115
+ To review it before execution, download successfully first, inspect the file, then run it:
116
+
117
+ ```bash
118
+ installer_dir=$(mktemp -d) &&
119
+ curl -fsSL https://pairmux.treeleaves30760.com/install.sh -o "$installer_dir/install.sh" &&
120
+ less "$installer_dir/install.sh" &&
121
+ bash "$installer_dir/install.sh"
122
+ ```
123
+
124
+ The one-line pipe executes downloaded code; it is not a substitute for that review. The installer
125
+ clears all inherited `UV_*` settings, ignores uv configuration, and uses **`https://pypi.org/simple`**
126
+ with no persistent cache and wheels only. Normal uv commands use your regular configuration. See
127
+ [installation guidance](https://pairmux-docs.treeleaves30760.com/#install)
128
+ for PATH setup and other supported methods (`pipx install pairmux` or `python -m pip install pairmux`
129
+ in a dedicated environment).
130
+
131
+ On Windows, the [PowerShell installer](https://pairmux.treeleaves30760.com/install.ps1) applies the
132
+ same PyPI-only uv policy natively, without administrator rights:
133
+
134
+ ```powershell
135
+ irm https://pairmux.treeleaves30760.com/install.ps1 | iex
136
+ ```
137
+
138
+ Set `$env:PAIRMUX_INSTALL_TARGET = 'wsl'` first to install into a WSL distribution instead.
139
+
140
+ ### Requirements
141
+
142
+ The [PyPI pairmux wheels](https://pypi.org/project/pairmux/) contain a prebuilt native Go binary,
143
+ so installation needs no Go toolchain or source build. Wheel installers require Python 3.9 or newer;
144
+ the installed `pairmux` executable itself contains no Python code. If needed, the installer obtains
145
+ uv from [Astral's official installer](https://docs.astral.sh/uv/getting-started/installation/), and
146
+ uv may obtain managed Python from Astral's upstream Python distributions. **Only the pairmux wheel
147
+ comes from PyPI in that installer flow; uv/Python may come from Astral upstream.**
148
+
149
+ PyPI package requirements and wheel targets:
150
+
151
+ - macOS 12+, manylinux_2_17 (glibc 2.17+), or Windows 10 version 1809+ (ConPTY)
152
+ - x86-64 or ARM64 (aarch64) on every operating system
153
+ - **tmux is optional.** On macOS and Linux, pairmux uses tmux when it is installed (the tmux
154
+ backend needs tmux 3.2 or newer, installed separately with your system package manager) and its
155
+ built-in multiplexer otherwise. Windows always uses the built-in multiplexer. Set
156
+ `PAIRMUX_BACKEND=builtin` or `PAIRMUX_BACKEND=tmux` to override the automatic choice. Neither
157
+ the wheels nor the installers supply tmux or run sudo to install it.
158
+ - WSL remains supported: inside WSL, pairmux installs and runs as on any other Linux system
159
+
160
+ ### From a source checkout, without PyPI
161
+
162
+ If you can clone the repository but cannot reach PyPI, install a development build from the clone
163
+ with no build dependencies: `python -m pip install .` or `uv tool install .` builds the binary with
164
+ a local Go 1.25+ toolchain, or packages a release binary you downloaded from
165
+ [GitHub Releases](https://github.com/treeleaves30760/pairmux/releases) when you set
166
+ `PAIRMUX_PREBUILT_BINARY` to its absolute path. Such builds get a development version and are not
167
+ `pairmux update` targets. See the
168
+ [source install guide](https://github.com/treeleaves30760/pairmux/blob/main/packaging/pypi/README.md#install-from-a-source-checkout).
169
+
170
+ The quickstart below assumes the persistent `pairmux` command is on PATH. For temporary use,
171
+ prefix each command with `uvx`.
172
+
173
+ ## 60-second quickstart
174
+
175
+ Create one managed terminal, then run commands in it:
176
+
177
+ ```bash
178
+ pairmux --json new --name demo
179
+ pairmux --json run demo "echo hello from pairmux"
180
+
181
+ # A timeout returns status=running; it does not kill the command.
182
+ pairmux --json run demo "sleep 2; echo finished" --timeout 1s
183
+
184
+ # When status is running, keep waiting without sleep-and-guess polling.
185
+ pairmux --json wait demo --idle 800
186
+ pairmux --json peek demo
187
+ ```
188
+
189
+ `wait --idle` refreshes terminal state after output becomes quiet; silence alone is not treated as
190
+ completion. `peek` and `log` are read-only, so other agents can inspect the same terminal without
191
+ taking its writer lock.
192
+
193
+ ## Teach your agent
194
+
195
+ pairmux embeds its Agent Skill, including the `new → run → wait/send/log` loop and safe human
196
+ handoff guidance:
197
+
198
+ ```bash
199
+ pairmux skill install --target codex --dry-run
200
+ pairmux skill install --target codex
201
+ ```
202
+
203
+ Use `--target all` to update only the supported agent configuration directories that already
204
+ exist. See the [Agent Skills guide](https://pairmux-docs.treeleaves30760.com/skills) for all
205
+ targets and install locations.
206
+
207
+ MCP clients can launch the built-in stdio server and use the core terminal operations as typed
208
+ tools:
209
+
210
+ ```json
211
+ {
212
+ "command": "pairmux",
213
+ "args": ["mcp", "serve"]
214
+ }
215
+ ```
216
+
217
+ ## Interactive work and human handoff
218
+
219
+ After 800 ms of output quiet, pairmux recognizes supported prompt patterns: confirmations,
220
+ password/passphrase/passcode prompts, pager markers, press-key messages, and Python's `>>>`. It
221
+ reports `awaiting-input` and never auto-answers. Replace the uppercase placeholders below before
222
+ sending ordinary input:
223
+
224
+ ```bash
225
+ pairmux send NAME --text VALUE --enter
226
+ ```
227
+
228
+ For a secret-shaped prompt, the response recommends `pairmux wait NAME --human --notify`. A human
229
+ can enter the same live pane with `pairmux attach NAME`, provide the input, and detach (on the tmux
230
+ backend, with the configured tmux binding, default `Ctrl-b d`; see the
231
+ [CLI reference](https://pairmux-docs.treeleaves30760.com/cli-reference) for the built-in backend).
232
+ Running `pairmux note NAME "ready"` afterward records a message and releases an agent waiting with `--human`; it does not itself detach or enforce
233
+ control ownership. This avoids routing the input through the agent-facing `send` command. Prompt
234
+ recognition is heuristic, desktop notification is best-effort, and whether an application echoes or
235
+ records input remains application-dependent.
236
+
237
+ ## How it works
238
+
239
+ A terminal multiplexer remains the terminal-state engine: tmux when it is installed on macOS or
240
+ Linux, otherwise pairmux's own built-in server, which drives a PTY on Unix and ConPTY on native
241
+ Windows. Short-lived pairmux commands add completion detection, captured output, model-friendly
242
+ shaping, and coordination around the live pane. `pairmux attach` connects a human to the same
243
+ managed terminal whenever a human needs to observe or take over.
244
+
245
+ pairmux is open source under the [MIT License](https://github.com/treeleaves30760/pairmux/blob/main/LICENSE).
@@ -0,0 +1,4 @@
1
+ pairmux-1.0.0.data/scripts/pairmux.exe,sha256=wr8otmnkmjht1xWKG_gjYwTWSGBPtBUeu0OTcBWGu1Q,4505600
2
+ pairmux-1.0.0.dist-info/METADATA,sha256=Hl4HB5TpnqPzkzv0QCF2fmQB9JRknG2rfcO0C-xY3iU,11683
3
+ pairmux-1.0.0.dist-info/WHEEL,sha256=BQYn4w-yyiuXGasbp6HtVU_SkpygIYY8Jevf0co8QLk,91
4
+ pairmux-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: pairmux-build
3
+ Root-Is-Purelib: false
4
+ Tag: py3-none-win_amd64