tui-input 0.1.0__tar.gz

tui_input-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,97 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill in as much detail as possible.
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "e.g., macOS 14.2, Ubuntu 24.04"
+    validations:
+      required: true
+
+  - type: input
+    id: terminal
+    attributes:
+      label: Terminal Emulator
+      placeholder: "e.g., iTerm2, Alacritty, WezTerm, Terminal.app"
+    validations:
+      required: true
+
+  - type: input
+    id: tmux-version
+    attributes:
+      label: tmux Version
+      description: "Output of `tmux -V`"
+      placeholder: "e.g., tmux 3.4"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: "Output of `python3 --version`"
+      placeholder: "e.g., Python 3.12.1"
+    validations:
+      required: true
+
+  - type: input
+    id: tui-input-version
+    attributes:
+      label: tui-input Version
+      description: "Output of `tui-input --version`"
+      placeholder: "e.g., tui-input 0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How to reproduce the behavior.
+      value: |
+        1. Run `tui-input ...`
+        2. Type '...'
+        3. Press ...
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: Any relevant logs or screenshots.
+    validations:
+      required: false

tui_input-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion! Please describe the feature you'd like to see.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve? What's the current limitation?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this to work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or workarounds you've considered.
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or references.
+    validations:
+      required: false

tui_input-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- Brief description of what this PR does and why -->
+
+## Changes
+
+<!-- Bulleted list of key changes -->
+
+-
+
+## Test Plan
+
+<!-- How to verify these changes work -->
+
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check src/ tests/` passes
+- [ ] `uv run mypy src/` passes
+- [ ] Manual testing in tmux (if applicable)
+
+## Checklist
+
+- [ ] Tests added/updated for new functionality
+- [ ] Documentation updated (if applicable)
+- [ ] CHANGELOG.md updated (if user-facing change)

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

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run mypy src/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest -v

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

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tui-input
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

tui_input-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tool caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Environment / secrets
+.env
+.env.*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Debug logs
+/tmp/tui-input-*.log

tui_input-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-14
+
+### Added
+
+- Initial release
+- Tmux-based split pane with companion input bar
+- Multi-line input with auto-resizing (3-10 lines)
+- Bracketed paste for safe text transfer
+- JSON-based input history with up/down navigation
+- Agent-agnostic design (works with any terminal command)
+- Auto-cleanup when the target pane exits
+- One-liner install script with agent detection and alias registration
+- Key bindings: Enter (send), Shift+Enter (newline), Esc (clear), arrows (history)
+
+[Unreleased]: https://github.com/maked-dev/tui-input/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/maked-dev/tui-input/releases/tag/v0.1.0

tui_input-0.1.0/CLAUDE.md

@@ -0,0 +1,43 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Build & Test Commands
+
+```bash
+uv run pytest tests/ -v          # Run all tests
+uv run pytest tests/ -v --cov    # Run with coverage
+uv run ruff check src/ tests/    # Lint
+uv run ruff format src/ tests/   # Format
+uv run mypy src/                 # Type check
+```
+
+## Architecture
+
+```
+cli.py          CLI entry point (argparse, dispatches to internal modes)
+  ↓
+launcher.py     Tmux environment setup (split pane, launch companion + agent)
+  ↓
+companion.py    Textual app — input bar widget with key forwarding
+  ↓
+tmux.py         Low-level tmux operations (pane queries, text pasting, hooks)
+history.py      JSON-based persistent input history
+```
+
+### Key Design Decisions
+
+- **Companion pane ID via `TMUX_PANE` env var**: `tmux display-message -p` returns the *selected* pane, not the pane the process runs in. Always use `os.environ.get("TMUX_PANE")` for the companion's own pane ID.
+- **Shell vs Direct mode**: Inside tmux, the pane runs a shell that spawns the agent. Outside tmux, the pane runs the agent directly. `_check_target_alive` uses `_is_shell()` to pick the right exit detection strategy.
+- **IME deferred actions**: Enter/Shift+Enter handlers use a 50ms timer to let terminal IME settle before acting. Terminal IME composition characters are NOT sent to the app — they exist only in the terminal's overlay.
+- **Separate paste + Enter**: `submit_to_pane` uses `paste-buffer` for text and `send-keys Enter` separately, so the target app reliably treats Enter as submit.
+- **Hook commands wrapped in `run-shell`**: tmux hooks expect tmux commands, not shell commands. Shell commands must be wrapped in `run-shell '...'`.
+- **Dynamic pane addressing**: Never use hardcoded pane indices (`.0`). Use `list-panes -F '#{pane_id}'` to handle any `pane-base-index` setting.
+
+## Conventions
+
+- Language: code identifiers in English, comments/docs in English
+- All modules use `from __future__ import annotations`
+- Type hints on all function signatures; `mypy --strict` must pass
+- `contextlib.suppress(subprocess.CalledProcessError)` over bare `except Exception`
+- Constants at module level, no magic numbers in logic

tui_input-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to tui-input
+
+Thanks for your interest in contributing! This guide will help you get started.
+
+## Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/maked-dev/tui-input.git
+   cd tui-input
+   ```
+
+2. **Install dependencies** (using [uv](https://github.com/astral-sh/uv)):
+   ```bash
+   uv sync
+   ```
+
+3. **Verify your setup:**
+   ```bash
+   uv run pytest
+   uv run ruff check src/ tests/
+   uv run mypy src/
+   ```
+
+## Code Style
+
+- **Formatter/Linter:** [Ruff](https://github.com/astral-sh/ruff) — configured in `pyproject.toml`
+- **Type checking:** [mypy](https://mypy-lang.org/) in strict mode
+- **Line length:** 100 characters
+- **Python version:** 3.10+ (use `from __future__ import annotations` in all modules)
+
+Run before committing:
+
+```bash
+uv run ruff check --fix src/ tests/
+uv run ruff format src/ tests/
+uv run mypy src/
+```
+
+## Testing
+
+- Tests live in `tests/`
+- Use [pytest](https://pytest.org/) with [pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio) for async tests
+- Textual apps are tested using [Textual's pilot API](https://textual.textualize.io/guide/testing/)
+- All tmux calls should be mocked — tests must not require tmux to be installed
+
+```bash
+uv run pytest              # Run all tests
+uv run pytest -x           # Stop on first failure
+uv run pytest -v           # Verbose output
+uv run pytest tests/test_history.py  # Run a specific test file
+```
+
+## Pull Request Process
+
+1. Fork the repo and create a feature branch from `main`
+2. Write tests for any new functionality
+3. Ensure all checks pass: `ruff check`, `ruff format --check`, `mypy`, `pytest`
+4. Write a clear PR description explaining **what** and **why**
+5. Keep PRs focused — one feature or fix per PR
+
+## Commit Messages
+
+- Use present tense ("Add feature" not "Added feature")
+- Keep the first line under 72 characters
+- Reference issues when applicable (e.g., "Fix #42")
+
+## Reporting Bugs
+
+Use the [bug report template](https://github.com/maked-dev/tui-input/issues/new?template=bug_report.yml) and include:
+
+- OS and terminal emulator
+- tmux version (`tmux -V`)
+- Python version (`python3 --version`)
+- Steps to reproduce
+
+## Feature Requests
+
+Use the [feature request template](https://github.com/maked-dev/tui-input/issues/new?template=feature_request.yml).

tui_input-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maked-dev
+
+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.

tui_input-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: tui-input
+Version: 0.1.0
+Summary: A terminal companion that pins a persistent input bar at the bottom of your tmux pane, so you can scroll freely through long TUI agent output while composing your response.
+Project-URL: Homepage, https://github.com/maked-dev/tui-input
+Project-URL: Repository, https://github.com/maked-dev/tui-input
+Project-URL: Issues, https://github.com/maked-dev/tui-input/issues
+Project-URL: Changelog, https://github.com/maked-dev/tui-input/blob/main/CHANGELOG.md
+Author: maked-dev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,claude,codex,input,terminal,tmux,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: textual>=0.85.0
+Description-Content-Type: text/markdown
+
+# tui-input
+
+[![CI](https://github.com/maked-dev/tui-input/actions/workflows/ci.yml/badge.svg)](https://github.com/maked-dev/tui-input/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tui-input)](https://pypi.org/project/tui-input/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A terminal companion that pins a persistent input bar at the bottom of your tmux pane. Scroll freely through long TUI agent output while composing your response.
+
+<!-- TODO: demo GIF -->
+<!-- ![demo](https://github.com/maked-dev/tui-input/assets/demo.gif) -->
+
+## The Problem
+
+When using TUI-based AI agents (Claude Code, Codex CLI, etc.), long outputs force you to scroll up to read, then scroll back down to type. You end up:
+
+- Losing your place in the output
+- Writing responses in a separate editor, then copy-pasting
+- Fighting the terminal scroll position
+
+## The Solution
+
+`tui-input` splits your terminal into two panes:
+
+```
+┌─────────────────────────────────────┐
+│  Top pane (Claude Code / Codex etc) │
+│  Scroll freely through long output  │
+├─────────────────────────────────────┤  ← 3-10 lines, auto-resizing
+│  Type your response here...         │
+│  Enter to send · Shift+Enter: newline│
+└─────────────────────────────────────┘
+```
+
+## Features
+
+- **Pinned input bar** — always visible at the bottom, regardless of scroll position
+- **Auto-resize** — companion grows from 3 to 10 lines as you type multi-line input
+- **Bracketed paste** — safe multi-line text transfer via tmux buffers
+- **Input history** — press `↑`/`↓` to recall previous inputs (persisted across sessions)
+- **Agent-agnostic** — works with any terminal program, not just AI agents
+- **Auto-cleanup** — companion exits when the agent exits
+
+## Installation
+
+### Requirements
+
+- Python 3.10+
+- tmux
+
+### Install via pip/uv
+
+```bash
+# Using uv (recommended)
+uv tool install tui-input
+
+# Using pip
+pip install tui-input
+```
+
+### One-liner (auto-detects agents + registers aliases)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/maked-dev/tui-input/main/install.sh | bash
+```
+
+This will:
+1. Install `tui-input`
+2. Detect installed agents (claude, codex, etc.)
+3. Register shell aliases so you can just type `claude` instead of `tui-input claude`
+
+To uninstall aliases:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/maked-dev/tui-input/main/install.sh | bash -s -- --uninstall
+```
+
+## Usage
+
+```bash
+# Basic usage
+tui-input claude
+
+# Any command works
+tui-input "vim file.py"
+tui-input htop
+
+# With aliases installed (via install.sh), just type the agent name
+claude
+codex
+```
+
+### Key Bindings
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Send text to top pane + clear input |
+| `Shift+Enter` | Insert newline (multi-line input) |
+| `↑` (on empty) | Previous history entry |
+| `↓` (on empty) | Next history entry |
+| `Esc` | Clear all input |
+
+### How It Works
+
+1. `tui-input` creates a tmux vertical split (or a new session if not in tmux)
+2. Your command runs in the top pane
+3. A Textual-based companion widget runs in the bottom pane
+4. Press `Enter` to send text to the top pane via `tmux paste-buffer`
+5. When the top pane command exits, the companion auto-exits
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/maked-dev/tui-input.git
+cd tui-input
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and format
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+
+# Type check
+uv run mypy src/
+```
+
+## License
+
+[MIT](LICENSE)