ctxttools 0.3.0__tar.gz → 0.3.1__tar.gz

{ctxttools-0.3.0/ctxttools.egg-info → ctxttools-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxttools
-Version: 0.3.0
+Version: 0.3.1
 Summary: CLI tools for LLM conversations
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -9,7 +9,7 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: tiktoken>=0.5.0
 Requires-Dist: structlog>=24.0
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.2.0; extra == "mcp"
+Requires-Dist: mcp<2.0,>=1.2.0; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Dynamic: license-file
@@ -65,6 +65,7 @@ As you can see, these are unix-friendly tools using simple paradigms that you ar
 | `cdir` | List sessions (ls for your history) | [docs/cdir.md](docs/cdir.md) |
 | `ccat` | Print one or more conversations (cat for your history) | [docs/ccat.md](docs/ccat.md) |
 | `ccopy` | Copy a whole conversation from one agent to a new session in another | [docs/ccopy.md](docs/ccopy.md) |
+| `crecover` | List, verify, and restore the storage backups ccopy takes before each write | [docs/crecover.md](docs/crecover.md) |
 | `cextract` | Extract concepts from a session into files, and inject them back | [docs/cextract.md](docs/cextract.md) |
 | `cconnect` | Live concept pipelines between sessions | [docs/cconnect.md](docs/cconnect.md) |
 | `cdu` | Token usage per session (du for context windows) | [docs/cdu.md](docs/cdu.md) |
@@ -104,6 +105,32 @@ graph LR
 
 Context windows are endpoints: opencode, Claude Code, Codex, Pi. They all speak different protocols, but they all consume the same packets. See [cextract](docs/cextract.md) for the concept packet format, strategies, and the filter configs (decision model and JSON-RPC).
 
+## Write safety
+
+The session-mover tools write into your agents' **live** storage — for the
+SQLite-backed agents (opencode, goose, kilo, hermes) that's the database that
+holds every session of that agent. A write that fails or is interrupted
+part-way can corrupt it, and losing an agent's whole history would be
+unforgivable.
+
+So every local write is guarded:
+
+1. ctools **snapshots the agent's storage first** (SQLite via `VACUUM INTO` —
+   a consistent copy even mid-write; file agents via a tree copy), kept under
+   `~/.local/share/ctools/backups/<agent>/` (20 newest per agent).
+2. After the write it **verifies** the storage: the DB opens,
+   `PRAGMA integrity_check` passes, the session table still exists, and the
+   session count did not decrease. A database that is structurally valid but
+   emptied of data is caught too.
+3. If anything looks wrong, the snapshot is **restored automatically** — you
+   get a clean error, not a broken database.
+
+And because a restore is itself a write, it snapshots what it overwrites, so
+**every restore is undoable**. For the out-of-band case (you notice days later
+that an agent's history vanished), `crecover list` / `verify` / `restore` are
+there. Details: [ccopy — safety](docs/ccopy.md#safety-automatic-backups) and
+[crecover](docs/crecover.md).
+
 ## Supported endpoints
 
 | Agent | Storage |
@@ -150,23 +177,47 @@ Anything the storage cannot do — pi's session trees cannot be rewritten in pla
 
 ## MCP server
 
-There is an MCP server for use from Claude, opencode, Cursor, or anything else that speaks MCP.
+There is an MCP server for use from pi, Claude, opencode, Cursor, or anything else that speaks MCP.
 
 Tools: `list_agents`, `list_sessions`, `search_sessions`, `export_session`, `extract_concepts`, `copy_concepts`, `get_session_concepts`.
 
-Add to your MCP config:
+### Quick install (pi)
+
+One command does the whole job — install into an isolated venv (if needed) and register with pi:
+
+```sh
+pipx run 'ctxttools[mcp]' ctools-mcp install
+# or, with uv:
+uv tool run 'ctxttools[mcp]' ctools-mcp install
+```
+
+It detects an existing `uv tool` or `pipx` install of `ctxttools` and uses it instead. Verify with:
+
+```sh
+pi mcp list   # expect: ctools: connected, 7 tools
+```
+
+Then use it inside pi — run `/mcp` to inspect, or just ask the agent (the tools are also reachable through codemode / tool search).
+
+Uninstall with `ctools-mcp uninstall` (removes the pi entry; pass `--all` to also remove Claude Code and opencode entries).
+
+### Other clients
+
+Run `ctools-mcp print-config` to get the JSON snippet for any MCP host, e.g. for opencode (`opencode.json` under `"mcp"`) or Claude (`.mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "ctools": {
       "command": "python",
-      "args": ["/ABSOLUTE/PATH/TO/ctools/ctools_mcp.py"]
+      "args": ["-m", "ctools.ctools_mcp"]
     }
   }
 }
 ```
 
+(`command` should point at the interpreter of a venv that has `ctxttools[mcp]` installed — `ctools-mcp install` prints the exact one for your machine.)
+
 ## Web dashboard
 
 Prefer a mouse to a man page? ctools ships a browser dashboard — a small local
@@ -174,26 +225,35 @@ web server (Python stdlib only, no web dependencies) with the same library
 underneath. Same on macOS, Windows, and Linux:
 
 ```sh
-$ ctools-web                 # or: python -m ctools.webui
+$ ctools-web                 # installed command
+# or, straight from a checkout, no install needed:
+$ python3 ctools/ctools-web.py        # or: python -m ctools.webui
 ctools 0.2.1 dashboard: http://127.0.0.1:8765
 ```
 
-Open the URL. You get four views:
+Open the URL. The navbar has **Overview**, **Sessions**, and **Concepts**, plus
+a search box (press <b>/</b>) and a power button to stop the server. Clicking a
+session anywhere opens its **Conversation** view:
 
 - **Overview** — every supported agent, installed or not, with session counts
   and total tokens, and a jump into each agent's sessions.
-- **Search** — `cgrep` in the browser: one regex box, per-agent chips, live
-  matches; click any match to open that conversation.
-- **Sessions** — `cdir` for one agent: newest, largest, or by token usage.
-- **Conversation** — `ccat` with the source session's messages, token usage,
-  the resume command, concept extraction (`cextract`), a markdown export,
-  and **Copy** — `ccopy` to any other installed agent, which creates a fresh
+- **Search** — `cgrep` in the browser: one box, searches session ids, names,
+  paths <b>and</b> the content of every conversation at once; click a match to
+  open that conversation.
+- **Sessions** — `cdir` for one agent (or all of them): newest, largest, or by
+  token usage, filterable.
+- **Conversation** — `ccat` with the session's messages, token usage, the
+  resume command, concept extraction (`cextract`), a markdown export, and
+  **Copy** — `ccopy` to any other installed agent, which creates a fresh
   session there (source untouched) and tells you how to resume it.
 
 The server binds to `127.0.0.1` by default, so nothing is exposed to your
 network unless you pass `--host 0.0.0.0`. There is one write operation:
 Copy. Everything else is read-only against the agents' storage.
 
+Stop it with **Ctrl-C**, or with the **power button** (⏻) in the top-right of
+the page — it asks for confirmation, then shuts the server down cleanly.
+
 ```sh
 ctools-web --port 9000
 ```

{ctxttools-0.3.0 → ctxttools-0.3.1}/README.md

@@ -49,6 +49,7 @@ As you can see, these are unix-friendly tools using simple paradigms that you ar
 | `cdir` | List sessions (ls for your history) | [docs/cdir.md](docs/cdir.md) |
 | `ccat` | Print one or more conversations (cat for your history) | [docs/ccat.md](docs/ccat.md) |
 | `ccopy` | Copy a whole conversation from one agent to a new session in another | [docs/ccopy.md](docs/ccopy.md) |
+| `crecover` | List, verify, and restore the storage backups ccopy takes before each write | [docs/crecover.md](docs/crecover.md) |
 | `cextract` | Extract concepts from a session into files, and inject them back | [docs/cextract.md](docs/cextract.md) |
 | `cconnect` | Live concept pipelines between sessions | [docs/cconnect.md](docs/cconnect.md) |
 | `cdu` | Token usage per session (du for context windows) | [docs/cdu.md](docs/cdu.md) |
@@ -88,6 +89,32 @@ graph LR
 
 Context windows are endpoints: opencode, Claude Code, Codex, Pi. They all speak different protocols, but they all consume the same packets. See [cextract](docs/cextract.md) for the concept packet format, strategies, and the filter configs (decision model and JSON-RPC).
 
+## Write safety
+
+The session-mover tools write into your agents' **live** storage — for the
+SQLite-backed agents (opencode, goose, kilo, hermes) that's the database that
+holds every session of that agent. A write that fails or is interrupted
+part-way can corrupt it, and losing an agent's whole history would be
+unforgivable.
+
+So every local write is guarded:
+
+1. ctools **snapshots the agent's storage first** (SQLite via `VACUUM INTO` —
+   a consistent copy even mid-write; file agents via a tree copy), kept under
+   `~/.local/share/ctools/backups/<agent>/` (20 newest per agent).
+2. After the write it **verifies** the storage: the DB opens,
+   `PRAGMA integrity_check` passes, the session table still exists, and the
+   session count did not decrease. A database that is structurally valid but
+   emptied of data is caught too.
+3. If anything looks wrong, the snapshot is **restored automatically** — you
+   get a clean error, not a broken database.
+
+And because a restore is itself a write, it snapshots what it overwrites, so
+**every restore is undoable**. For the out-of-band case (you notice days later
+that an agent's history vanished), `crecover list` / `verify` / `restore` are
+there. Details: [ccopy — safety](docs/ccopy.md#safety-automatic-backups) and
+[crecover](docs/crecover.md).
+
 ## Supported endpoints
 
 | Agent | Storage |
@@ -134,23 +161,47 @@ Anything the storage cannot do — pi's session trees cannot be rewritten in pla
 
 ## MCP server
 
-There is an MCP server for use from Claude, opencode, Cursor, or anything else that speaks MCP.
+There is an MCP server for use from pi, Claude, opencode, Cursor, or anything else that speaks MCP.
 
 Tools: `list_agents`, `list_sessions`, `search_sessions`, `export_session`, `extract_concepts`, `copy_concepts`, `get_session_concepts`.
 
-Add to your MCP config:
+### Quick install (pi)
+
+One command does the whole job — install into an isolated venv (if needed) and register with pi:
+
+```sh
+pipx run 'ctxttools[mcp]' ctools-mcp install
+# or, with uv:
+uv tool run 'ctxttools[mcp]' ctools-mcp install
+```
+
+It detects an existing `uv tool` or `pipx` install of `ctxttools` and uses it instead. Verify with:
+
+```sh
+pi mcp list   # expect: ctools: connected, 7 tools
+```
+
+Then use it inside pi — run `/mcp` to inspect, or just ask the agent (the tools are also reachable through codemode / tool search).
+
+Uninstall with `ctools-mcp uninstall` (removes the pi entry; pass `--all` to also remove Claude Code and opencode entries).
+
+### Other clients
+
+Run `ctools-mcp print-config` to get the JSON snippet for any MCP host, e.g. for opencode (`opencode.json` under `"mcp"`) or Claude (`.mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "ctools": {
       "command": "python",
-      "args": ["/ABSOLUTE/PATH/TO/ctools/ctools_mcp.py"]
+      "args": ["-m", "ctools.ctools_mcp"]
     }
   }
 }
 ```
 
+(`command` should point at the interpreter of a venv that has `ctxttools[mcp]` installed — `ctools-mcp install` prints the exact one for your machine.)
+
 ## Web dashboard
 
 Prefer a mouse to a man page? ctools ships a browser dashboard — a small local
@@ -158,26 +209,35 @@ web server (Python stdlib only, no web dependencies) with the same library
 underneath. Same on macOS, Windows, and Linux:
 
 ```sh
-$ ctools-web                 # or: python -m ctools.webui
+$ ctools-web                 # installed command
+# or, straight from a checkout, no install needed:
+$ python3 ctools/ctools-web.py        # or: python -m ctools.webui
 ctools 0.2.1 dashboard: http://127.0.0.1:8765
 ```
 
-Open the URL. You get four views:
+Open the URL. The navbar has **Overview**, **Sessions**, and **Concepts**, plus
+a search box (press <b>/</b>) and a power button to stop the server. Clicking a
+session anywhere opens its **Conversation** view:
 
 - **Overview** — every supported agent, installed or not, with session counts
   and total tokens, and a jump into each agent's sessions.
-- **Search** — `cgrep` in the browser: one regex box, per-agent chips, live
-  matches; click any match to open that conversation.
-- **Sessions** — `cdir` for one agent: newest, largest, or by token usage.
-- **Conversation** — `ccat` with the source session's messages, token usage,
-  the resume command, concept extraction (`cextract`), a markdown export,
-  and **Copy** — `ccopy` to any other installed agent, which creates a fresh
+- **Search** — `cgrep` in the browser: one box, searches session ids, names,
+  paths <b>and</b> the content of every conversation at once; click a match to
+  open that conversation.
+- **Sessions** — `cdir` for one agent (or all of them): newest, largest, or by
+  token usage, filterable.
+- **Conversation** — `ccat` with the session's messages, token usage, the
+  resume command, concept extraction (`cextract`), a markdown export, and
+  **Copy** — `ccopy` to any other installed agent, which creates a fresh
   session there (source untouched) and tells you how to resume it.
 
 The server binds to `127.0.0.1` by default, so nothing is exposed to your
 network unless you pass `--host 0.0.0.0`. There is one write operation:
 Copy. Everything else is read-only against the agents' storage.
 
+Stop it with **Ctrl-C**, or with the **power button** (⏻) in the top-right of
+the page — it asks for confirmation, then shuts the server down cleanly.
+
 ```sh
 ctools-web --port 9000
 ```

{ctxttools-0.3.0 → ctxttools-0.3.1}/ctools/backup.py

@@ -27,12 +27,12 @@ import json
 import shutil
 import sqlite3
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import List, Optional
 
-from ctools.agents import Agent, AgentError
+from ctools.agents import Agent
 
 __all__ = [
     "BackupError", "Backup", "Backups",
@@ -194,14 +194,15 @@ def _session_table(agent: Agent) -> Optional[str]:
         try:
             conn = sqlite3.connect(str(agent.storage_path))
             try:
-                conn.execute(
+                row = conn.execute(
                     "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
                     (name,)).fetchone()
-                return name
             finally:
                 conn.close()
         except sqlite3.Error:
-            continue
+            row = None
+        if row is not None:
+            return name
     return None
 
 
@@ -342,7 +343,9 @@ class Backups:
                     out.append(Backup.load(child))
                 except (OSError, json.JSONDecodeError, KeyError):
                     continue  # skip a torn/corrupt manifest
-        out.sort(key=lambda b: b.when, reverse=True)
+        # `when` has second precision; the dir name encodes milliseconds and
+        # a collision counter, so it breaks same-second ties in creation order.
+        out.sort(key=lambda b: (b.when, b.path.name), reverse=True)
         return out
 
     def all(self) -> List[Backup]:
@@ -351,7 +354,7 @@ class Backups:
             for child in self.root.iterdir():
                 if child.is_dir():
                     out.extend(self.for_agent(child.name))
-        out.sort(key=lambda b: b.when, reverse=True)
+        out.sort(key=lambda b: (b.when, b.path.name), reverse=True)
         return out
 
     def prune(self, agent_name: str, keep: int) -> int:

{ctxttools-0.3.0 → ctxttools-0.3.1}/ctools/ccat.py

@@ -37,6 +37,7 @@ from rich.console import Console
 from rich.text import Text
 
 from ctools.agents import REGISTRY as AGENTS, SessionNotFound, get_agent
+from ctools.lib import install_clean_sigint
 from ctools.cli import (handle_version, parse_ref, parse_remote_ref, reporting,
                         version_option)
 from ctools.ccopy import _local_agent, _pull, _remote_common_doc, _remote_has_ctools
@@ -210,6 +211,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv=None) -> int:
+    install_clean_sigint()
     args = build_parser().parse_args(argv)
     if (v := handle_version(args)) is not None:
         return v

{ctxttools-0.3.0 → ctxttools-0.3.1}/ctools/ccopy.py

@@ -38,6 +38,7 @@ from ctools.agents import (
     Agent, Message, REGISTRY,
     get_agent, get_resume_command, SessionNotFound, UnsupportedOperation,
 )
+from ctools.lib import install_clean_sigint
 from ctools.cli import (Remote, handle_version, parse_ref, parse_remote_ref,
                         version_option)
 from ctools.backup import guard_write, BackupError
@@ -475,6 +476,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv=None) -> int:
+    install_clean_sigint()
     args = build_parser().parse_args(argv)
     if (v := handle_version(args)) is not None:
         return v