ferry-tui 0.1.1__tar.gz

ferry_tui-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+dist/
+demo/_frames/
+*.egg-info/
+.DS_Store

ferry_tui-0.1.1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.1
+
+- First public release from a fresh repository history.
+- Entirely synthetic demo and test conversations.
+- Cropped demo, readable Markdown previews, and narrow-terminal layout.
+- Generated Codex transfers require CLI resume to avoid an empty desktop chat.
+- Local search, linked conversation history, transfer modes, archive/undo, and read-only MCP.
+- Offline switch disables model-assisted titles, tags, and summaries.
+
+Known limits: Cowork is read-only; there is no GUI/CLI toggle; adapter checks do not establish compatibility with every vendor release. OpenCode is supported through handoff but has not been exercised against a live OpenCode installation in this release.

ferry_tui-0.1.1/LICENSE

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

ferry_tui-0.1.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: ferry-tui
+Version: 0.1.1
+Summary: One window for every AI coding conversation on this machine. List, search, preview, open, and carry a thread across to the other agent.
+Project-URL: Homepage, https://github.com/a-ghanim/ferry-tui
+Project-URL: Issues, https://github.com/a-ghanim/ferry-tui/issues
+Author: Abdou Ghanim
+License: MIT
+License-File: LICENSE
+Keywords: claude,codex,handoff,mcp,opencode,sessions,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: click<9,>=8.1
+Requires-Dist: handoff-agent==0.1.3
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: textual<9,>=8.2.8
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ferry
+
+A little boat for your AI coding conversations. Search your local history, pick up where you left off, or carry a conversation from one agent to another.
+
+![Ferry using entirely fictional conversations](https://raw.githubusercontent.com/a-ghanim/ferry-tui/main/demo/ferry.gif)
+
+## Install
+
+```sh
+uv tool install git+https://github.com/a-ghanim/ferry-tui@v0.1.1
+ferry
+```
+
+Requires Python 3.10 or newer and an existing supported agent store. Ferry is an early release, tested on macOS. The receiving agent's CLI must be installed and authenticated to continue a transferred conversation.
+
+## Use
+
+| Key | Action |
+| --- | --- |
+| Enter | Open the selected conversation in its agent |
+| Tab | Transfer context to another agent, then open it |
+| / | Search titles and message text |
+| p | Focus the transcript; switch panes in a narrow terminal |
+| e | Expand linked sessions in a conversation |
+| Space | Select multiple conversations |
+| r / t | Rename / edit tags |
+| d / u | Archive / undo the last Ferry write |
+| 2 | Create a second opinion in the other available agents |
+| q | Quit |
+
+The transfer dialog shows the source, message and token estimates, target agent, and working folders. Choose raw context, compact context without tool calls/results/reasoning, or a brief summary. Ferry groups the resulting sessions together and marks where the context came from. A transfer carries recorded conversation text and available artifacts; it does not preserve a model's hidden state, running tools, permissions, or unsaved files.
+
+## CLI and desktop behavior
+
+Existing native Codex threads open in the desktop app on macOS, with CLI fallback where no desktop opener is available. Ferry-generated Codex sessions use `codex resume`: the synthetic history used by this adapter is not reliably displayed as prior chat bubbles in the desktop app. Ferry refuses to open these through the app when the CLI is missing. There is currently no UI/CLI preference toggle.
+
+Claude Code opens with `claude --remote-control --resume`. Remote Control availability depends on Claude Code and your account. Cowork sessions are read-only; transfer their context to a writable agent to continue.
+
+## Local storage and privacy
+
+Ferry imports [Jackson Clark's handoff](https://github.com/HacksonClark/handoff) as a Python library. Its extractors and injectors convert agent records through a canonical transcript. Ferry adds search, titles, linked session history, transfer checks, and the interface.
+
+| Store | Read from | Transfer writes |
+| --- | --- | --- |
+| Codex | `~/.codex/sessions/` and `session_index.jsonl` | New rollout; SQLite registration when the agent database exists |
+| Claude Code, including desktop Code sessions in this store | `~/.claude/projects/` | New session under the selected folder |
+| Claude Cowork | macOS Claude local-agent-mode-sessions store | Read-only |
+| OpenCode | handoff's configured OpenCode store | Through handoff's adapter |
+
+The searchable user/assistant text stays in `~/.cache/ferry/index.db`. There is no hosted Ferry backend. The cache is sensitive even after automatic secret redaction; redaction is best-effort and does not anonymize conversations. `ferry exclude <handle>` removes a conversation from searchable text. Archive and undo files also live in this directory, so do not delete the cache if you need those files back.
+
+Ferry preserves transfer sources, refuses recently modified sessions, redacts known secret patterns, checks that the target adapter can read the new session, and logs writes for `ferry undo`. A successful adapter check is not a guarantee of compatibility with every future agent version.
+
+Missing titles can be generated through your authenticated `claude -p`, which sends excerpts to Claude. Brief summaries and requested tag suggestions also use Claude. Normal indexing/search does not need a model. Use `FERRY_OFFLINE=1 ferry` to disable these model-assisted features and use local fallback labels/summaries.
+
+## MCP
+
+```sh
+ferry mcp          # local stdio transport
+ferry mcp-config   # client configuration examples
+```
+
+The read-only tools are `search_conversations` and `get_conversation`. Results label retrieved transcripts as data, not instructions. Configure this server only in clients you intend to give archive access. Optional `ferry mcp --http 8765` binds to localhost; do not expose it publicly without a separate authenticated access layer.
+
+## Development
+
+```sh
+uv sync --extra dev
+uv run pytest -q
+uv build
+```
+
+Public tests construct fictional transcripts in temporary stores. No personal conversation fixtures or previous private Git history are included. `demo/make_gif.py` records the real UI and a verified transfer using fictional data; agent launch is disabled, and the transfer is undone. It needs macOS Quick Look and ffmpeg.
+
+## Credits
+
+handoff supplies extraction, injection, redaction, and its plugin registry. Ferry's Cowork reader registers through that plugin API. Design influences include claude-codex-bridge (lineage), session-porter (transfer modes), showagent (transfer previews), CASR (read-back checks), cct (folder remapping), Waybill, and syne. Ferry is independently maintained and is not an official OpenAI or Anthropic product.
+
+MIT.

ferry_tui-0.1.1/README.md

@@ -0,0 +1,79 @@
+# ferry
+
+A little boat for your AI coding conversations. Search your local history, pick up where you left off, or carry a conversation from one agent to another.
+
+![Ferry using entirely fictional conversations](https://raw.githubusercontent.com/a-ghanim/ferry-tui/main/demo/ferry.gif)
+
+## Install
+
+```sh
+uv tool install git+https://github.com/a-ghanim/ferry-tui@v0.1.1
+ferry
+```
+
+Requires Python 3.10 or newer and an existing supported agent store. Ferry is an early release, tested on macOS. The receiving agent's CLI must be installed and authenticated to continue a transferred conversation.
+
+## Use
+
+| Key | Action |
+| --- | --- |
+| Enter | Open the selected conversation in its agent |
+| Tab | Transfer context to another agent, then open it |
+| / | Search titles and message text |
+| p | Focus the transcript; switch panes in a narrow terminal |
+| e | Expand linked sessions in a conversation |
+| Space | Select multiple conversations |
+| r / t | Rename / edit tags |
+| d / u | Archive / undo the last Ferry write |
+| 2 | Create a second opinion in the other available agents |
+| q | Quit |
+
+The transfer dialog shows the source, message and token estimates, target agent, and working folders. Choose raw context, compact context without tool calls/results/reasoning, or a brief summary. Ferry groups the resulting sessions together and marks where the context came from. A transfer carries recorded conversation text and available artifacts; it does not preserve a model's hidden state, running tools, permissions, or unsaved files.
+
+## CLI and desktop behavior
+
+Existing native Codex threads open in the desktop app on macOS, with CLI fallback where no desktop opener is available. Ferry-generated Codex sessions use `codex resume`: the synthetic history used by this adapter is not reliably displayed as prior chat bubbles in the desktop app. Ferry refuses to open these through the app when the CLI is missing. There is currently no UI/CLI preference toggle.
+
+Claude Code opens with `claude --remote-control --resume`. Remote Control availability depends on Claude Code and your account. Cowork sessions are read-only; transfer their context to a writable agent to continue.
+
+## Local storage and privacy
+
+Ferry imports [Jackson Clark's handoff](https://github.com/HacksonClark/handoff) as a Python library. Its extractors and injectors convert agent records through a canonical transcript. Ferry adds search, titles, linked session history, transfer checks, and the interface.
+
+| Store | Read from | Transfer writes |
+| --- | --- | --- |
+| Codex | `~/.codex/sessions/` and `session_index.jsonl` | New rollout; SQLite registration when the agent database exists |
+| Claude Code, including desktop Code sessions in this store | `~/.claude/projects/` | New session under the selected folder |
+| Claude Cowork | macOS Claude local-agent-mode-sessions store | Read-only |
+| OpenCode | handoff's configured OpenCode store | Through handoff's adapter |
+
+The searchable user/assistant text stays in `~/.cache/ferry/index.db`. There is no hosted Ferry backend. The cache is sensitive even after automatic secret redaction; redaction is best-effort and does not anonymize conversations. `ferry exclude <handle>` removes a conversation from searchable text. Archive and undo files also live in this directory, so do not delete the cache if you need those files back.
+
+Ferry preserves transfer sources, refuses recently modified sessions, redacts known secret patterns, checks that the target adapter can read the new session, and logs writes for `ferry undo`. A successful adapter check is not a guarantee of compatibility with every future agent version.
+
+Missing titles can be generated through your authenticated `claude -p`, which sends excerpts to Claude. Brief summaries and requested tag suggestions also use Claude. Normal indexing/search does not need a model. Use `FERRY_OFFLINE=1 ferry` to disable these model-assisted features and use local fallback labels/summaries.
+
+## MCP
+
+```sh
+ferry mcp          # local stdio transport
+ferry mcp-config   # client configuration examples
+```
+
+The read-only tools are `search_conversations` and `get_conversation`. Results label retrieved transcripts as data, not instructions. Configure this server only in clients you intend to give archive access. Optional `ferry mcp --http 8765` binds to localhost; do not expose it publicly without a separate authenticated access layer.
+
+## Development
+
+```sh
+uv sync --extra dev
+uv run pytest -q
+uv build
+```
+
+Public tests construct fictional transcripts in temporary stores. No personal conversation fixtures or previous private Git history are included. `demo/make_gif.py` records the real UI and a verified transfer using fictional data; agent launch is disabled, and the transfer is undone. It needs macOS Quick Look and ffmpeg.
+
+## Credits
+
+handoff supplies extraction, injection, redaction, and its plugin registry. Ferry's Cowork reader registers through that plugin API. Design influences include claude-codex-bridge (lineage), session-porter (transfer modes), showagent (transfer previews), CASR (read-back checks), cct (folder remapping), Waybill, and syne. Ferry is independently maintained and is not an official OpenAI or Anthropic product.
+
+MIT.

ferry_tui-0.1.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ferry-tui"
+version = "0.1.1"
+description = "One window for every AI coding conversation on this machine. List, search, preview, open, and carry a thread across to the other agent."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Abdou Ghanim" }]
+keywords = ["claude", "codex", "opencode", "handoff", "tui", "sessions", "mcp"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development",
+]
+dependencies = [
+  "handoff-agent==0.1.3",
+  "textual>=8.2.8,<9",
+  "click>=8.1,<9",
+  "mcp>=2.2,<3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+ferry = "ferry.cli:main"
+
+[project.entry-points."handoff.agents"]
+claude-cowork = "ferry.plugins.claude_cowork:register"
+
+[project.urls]
+Homepage = "https://github.com/a-ghanim/ferry-tui"
+Issues = "https://github.com/a-ghanim/ferry-tui/issues"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md", "/pyproject.toml"]
+exclude = ["**/__pycache__/**", "**/*.pyc"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ferry"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ferry_tui-0.1.1/src/ferry/__init__.py

@@ -0,0 +1,3 @@
+"""ferry — one window for every AI coding conversation on this machine."""
+
+__version__ = "0.1.1"