ctxttools 0.2.1__tar.gz → 0.3.1__tar.gz

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

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: ctxttools
-Version: 0.2.1
+Version: 0.3.1
 Summary: CLI tools for LLM conversations
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.MIT
-Requires-Dist: typer>=0.9.0
 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
@@ -25,9 +24,9 @@ Dynamic: license-file
 </p>
 
 ------
-**ctools** is a suite of simple tools for navigating through the sessions in various agents. It allows you to search your history, transfer conversations, filter them, and even share them among hosts and users through ssh.
+**ctools** is a suite of simple tools for navigating through the sessions of the most popular LLM agents and coding tools. It allows you to search your history, transfer conversations, filter them, and even share them among machines and users.
 
-It supports [Claude Desktop](https://claude.com/download), [Claude Code](https://github.com/anthropics/claude-code), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [Hermes](https://github.com/NousResearch/hermes-agent), [Goose](https://github.com/aaif-goose/goose), [Kilo](https://github.com/Kilo-Org/kilocode), [Hermes](https://github.com/NousResearch/hermes-agent), [FreeBuff](https://github.com/CodebuffAI/freebuff), [Cline](https://github.com/cline/cline), and [omp](https://github.com/can1357/oh-my-pi).
+It supports [Claude Desktop](https://claude.com/download), [Claude Code](https://github.com/anthropics/claude-code), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [Hermes](https://github.com/NousResearch/hermes-agent), [Goose](https://github.com/aaif-goose/goose), [Kilo](https://github.com/Kilo-Org/kilocode), [FreeBuff](https://github.com/CodebuffAI/freebuff), [Cline](https://github.com/cline/cline), [omp](https://github.com/can1357/oh-my-pi), and [OpenClaw](https://openclaw.ai/).
 
 Here's an example:
 
@@ -58,38 +57,6 @@ Resume it with:
 
 As you can see, these are unix-friendly tools using simple paradigms that you are already familiar with.
 
-----
-
-### 1. `cgrep` — find it in your past conversations
-
-You already know the answer is in a session you had months ago. You just don't remember which one. `cgrep` searches **every session you ever had, across every agent you use**, with a plain regex:
-
-```shell
-$ cgrep -i "ssl"
-claude-code/a351eedf:142:assistant: … the TLS handshake fails with SSL wrong version number …
-opencode/ses_000d460f:16:user: ok graflex has an erorr in the check. i see this: … [[SSL: WRONG_VERSION_NUMBER] …
-opencode/ses_000d460f:34:assistant: Found it. Root cause: `_check_host` (graflex/__init__.py:128) tries `http`, and …
-```
-
-No agent argument? It searches **every installed agent at once** — Claude Code, Opencode, Kilo, Codex, Pi, Goose, Hermes, Cline, omp, and Freebuff, all in one pass. That last line is the root-cause analysis you wrote six months ago and would never have found again.
-
-### 2. `ccopy` — move your project from one tool to another
-
-Switched from opencode to Claude Code mid-project? You don't have to start from zero. Copy the whole conversation — context, decisions, the lot — into a fresh session in the other tool:
-
-```shell
-$ ccopy opencode/ses_abc123 claude-code
-Copied 128 message(s) from opencode/ses_abc123 to a new claude-code session: 1a2b3c
-Resume it with:
-  claude-code --resume 1a2b3c
-```
-
-Your work travels with you. The source is never touched, so it's a true copy. And when the destination is on another machine, it's just `ccopy opencode/ses_abc123 ssh://chris@remote/codex` — it pulls the agent's storage over your normal ssh (the remote only needs `sshd` and `tar`, not ctools).
-
-ctools is a set of GNU-style tools for the history your coding agents leave behind. These two are the headline; the rest (`cdir` to list sessions, `ccat` to read them, `cextract` to move concepts, `cconnect` to pipe them live, `cdu` to count tokens, `crm` to prune) are in service of them.
-
-**Works with the agents you already use:** Claude Desktop, Claude Code, Opencode, Kilo, Codex, Pi, Goose, Hermes, Cline, omp (oh-my-pi), and Freebuff (Codebuff).
-
 ## Tools
 
 | Tool | What it does | Docs |
@@ -98,13 +65,21 @@ ctools is a set of GNU-style tools for the history your coding agents leave behi
 | `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) |
 | `crm` | Remove concepts from a session (mdel) | [docs/crm.md](docs/crm.md) |
+| `ctools-web` | Browser dashboard for all of the above | [Web dashboard](#web-dashboard) |
 
 Every tool takes `--version`. The session-mover tools (`ccopy`, `cextract`, `cconnect`, `crm`) also take `--verbose` for structured logging. Each tool's full flag reference, output formats, and examples live in its `docs/` page — the table above is just the 30-second version.
 
+## The problem
+
+You talk to LLMs all day. Over weeks, you build up a set of constraints, preferences, and goals. These live in your conversations as system messages. They are valuable. They are also trapped.
+
+Say you have been working with opencode for a month. You have refined your coding style through dozens of sessions. Now you start a new Claude Code project and you want those same preferences. You could copy them by hand. Or you could `cextract` them out and `cextract` them back in, or copy the whole conversation across with `ccopy`. Either way, your memory travels with you.
+
 ## How it works
 
 ctools is a substrate for moving memory between context windows. Cross-platform, agent-agnostic, designed like a bus.
@@ -114,6 +89,8 @@ Two stages: **extraction** and **filtering**.
 - A **strategy** extracts concepts from a conversation. It defines what counts as a concept and how to find it: regex patterns, LLM extraction, whatever. Different strategies produce different ontologies from the same conversation, because context is contestable.
 - A **filter** selects which extracted concepts reach a destination. It's a binary classifier: pass through or filter out. One concept list can fan out to many destinations, each with its own filter. A coding agent gets coding preferences, a security agent gets security constraints, a PM agent gets goals, all from the same source.
 
+A filter can be as simple as a type or substring match, or as smart as a **decision model** — a small local classifier that scores each concept and lets it through only when confident. Point a filter at a model and you get *semantic* filtering with no free text to parse: ask "is this concept about security?" and gate on the answer. The model is asked either through Ollama's typed `/v1/systemone` endpoint (calibrated probabilities, the home of decision-dedicated models) or through any OpenAI-compatible `/v1/chat/completions` server (portable, lettered decision-task prompt) — one `endpoint` field decides. See [cextract](docs/cextract.md) for the decision-model and JSON-RPC filter configs.
+
 ```mermaid
 graph LR
     SRC["source session"] --> STRAT["strategy<br/>(extraction)"]
@@ -126,13 +103,33 @@ graph LR
     FC --> DEST_C["destination C"]
 ```
 
-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 (JSON-RPC) protocol.
+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).
 
-## The problem
+## Write safety
 
-You talk to LLMs all day. Over weeks, you build up a set of constraints, preferences, and goals. These live in your conversations as system messages. They are valuable. They are also trapped.
+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.
 
-Say you have been working with opencode for a month. You have refined your coding style through dozens of sessions. Now you start a new Claude Code project and you want those same preferences. You could copy them by hand. Or you could `cextract` them out and `cextract` them back in, or copy the whole conversation across with `ccopy`. Either way, your memory travels with you.
+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
 
@@ -149,6 +146,12 @@ Say you have been working with opencode for a month. You have refined your codin
 | cline | JSON (`~/.cline/data/tasks/`) |
 | omp | JSONL (`~/.omp/agent/sessions/`, tree journal) |
 | freebuff | JSON (`~/.config/<codebuff>/projects/`) |
+| openclaw | SQLite (per-agent, `~/.openclaw/agents/`, `OPENCLAW_STATE_DIR`) |
+
+OpenClaw is a **personal assistant** rather than a terminal coding agent, so it
+runs in a local Gateway that owns its store; ctools reads and exports its
+sessions but does not seed new ones (the store has canonical-index and integrity
+checks that a raw insert cannot satisfy).
 
 Run `cdir` to see which endpoints are found on your system and where they store data.
 
@@ -174,23 +177,87 @@ 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
+web server (Python stdlib only, no web dependencies) with the same library
+underneath. Same on macOS, Windows, and Linux:
+
+```sh
+$ 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. 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 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
+```
+
 ## Installation
 
 ```sh
@@ -213,7 +280,7 @@ from ctools.lib import get_formatter
 from ctools.cgrep import grep_session
 from ctools.cextract import extract_concepts_from_messages
 from ctools.cdu import count_tokens, get_session_tokens
-from ctools.filterlib import JSONRPCFilter, load_filter
+from ctools.filterlib import JSONRPCFilter, SystemOneFilter, load_filter
 from ctools.log import configure_logging, get_logger
 ```
 
@@ -238,6 +305,13 @@ from ctools.agents import OpencodeAgent
 agent = OpencodeAgent('/backup/opencode')
 ```
 
+## Where to go next
+
+- **Per-tool reference** — the [Tools](#tools) table above links to a `docs/` page for each command: every flag, output format, and a worked example.
+- **The interchange format** — how a conversation becomes a portable, lossless envelope and back, and why 2N agents compose into N² transfers. See [interchange](docs/interchange.md).
+- **Filtering with decision models** — the full decision-model and JSON-RPC filter configs, with live examples. See [cextract](docs/cextract.md#filters) and [cconnect](docs/cconnect.md#filter-configuration).
+- **Adding an endpoint** — one `Agent` subclass plus a line in `AGENT_CLASSES`. See [Supported endpoints](#supported-endpoints).
+
 ## Credits
 
 ctools was extracted from [Gab n' Go](https://github.com/day50-dev/gabngo). It's named after [GNU mtools](https://www.gnu.org/software/mtools/), which does the same thing for DOS floppies — because your context window is about the size of a DOS-floppy. The flag habits are GNU's too: `--version`, `-1`, `-S`, `-u`, and the rest behave the way you'd expect.

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

@@ -8,9 +8,9 @@
 </p>
 
 ------
-**ctools** is a suite of simple tools for navigating through the sessions in various agents. It allows you to search your history, transfer conversations, filter them, and even share them among hosts and users through ssh.
+**ctools** is a suite of simple tools for navigating through the sessions of the most popular LLM agents and coding tools. It allows you to search your history, transfer conversations, filter them, and even share them among machines and users.
 
-It supports [Claude Desktop](https://claude.com/download), [Claude Code](https://github.com/anthropics/claude-code), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [Hermes](https://github.com/NousResearch/hermes-agent), [Goose](https://github.com/aaif-goose/goose), [Kilo](https://github.com/Kilo-Org/kilocode), [Hermes](https://github.com/NousResearch/hermes-agent), [FreeBuff](https://github.com/CodebuffAI/freebuff), [Cline](https://github.com/cline/cline), and [omp](https://github.com/can1357/oh-my-pi).
+It supports [Claude Desktop](https://claude.com/download), [Claude Code](https://github.com/anthropics/claude-code), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [Hermes](https://github.com/NousResearch/hermes-agent), [Goose](https://github.com/aaif-goose/goose), [Kilo](https://github.com/Kilo-Org/kilocode), [FreeBuff](https://github.com/CodebuffAI/freebuff), [Cline](https://github.com/cline/cline), [omp](https://github.com/can1357/oh-my-pi), and [OpenClaw](https://openclaw.ai/).
 
 Here's an example:
 
@@ -41,38 +41,6 @@ Resume it with:
 
 As you can see, these are unix-friendly tools using simple paradigms that you are already familiar with.
 
-----
-
-### 1. `cgrep` — find it in your past conversations
-
-You already know the answer is in a session you had months ago. You just don't remember which one. `cgrep` searches **every session you ever had, across every agent you use**, with a plain regex:
-
-```shell
-$ cgrep -i "ssl"
-claude-code/a351eedf:142:assistant: … the TLS handshake fails with SSL wrong version number …
-opencode/ses_000d460f:16:user: ok graflex has an erorr in the check. i see this: … [[SSL: WRONG_VERSION_NUMBER] …
-opencode/ses_000d460f:34:assistant: Found it. Root cause: `_check_host` (graflex/__init__.py:128) tries `http`, and …
-```
-
-No agent argument? It searches **every installed agent at once** — Claude Code, Opencode, Kilo, Codex, Pi, Goose, Hermes, Cline, omp, and Freebuff, all in one pass. That last line is the root-cause analysis you wrote six months ago and would never have found again.
-
-### 2. `ccopy` — move your project from one tool to another
-
-Switched from opencode to Claude Code mid-project? You don't have to start from zero. Copy the whole conversation — context, decisions, the lot — into a fresh session in the other tool:
-
-```shell
-$ ccopy opencode/ses_abc123 claude-code
-Copied 128 message(s) from opencode/ses_abc123 to a new claude-code session: 1a2b3c
-Resume it with:
-  claude-code --resume 1a2b3c
-```
-
-Your work travels with you. The source is never touched, so it's a true copy. And when the destination is on another machine, it's just `ccopy opencode/ses_abc123 ssh://chris@remote/codex` — it pulls the agent's storage over your normal ssh (the remote only needs `sshd` and `tar`, not ctools).
-
-ctools is a set of GNU-style tools for the history your coding agents leave behind. These two are the headline; the rest (`cdir` to list sessions, `ccat` to read them, `cextract` to move concepts, `cconnect` to pipe them live, `cdu` to count tokens, `crm` to prune) are in service of them.
-
-**Works with the agents you already use:** Claude Desktop, Claude Code, Opencode, Kilo, Codex, Pi, Goose, Hermes, Cline, omp (oh-my-pi), and Freebuff (Codebuff).
-
 ## Tools
 
 | Tool | What it does | Docs |
@@ -81,13 +49,21 @@ ctools is a set of GNU-style tools for the history your coding agents leave behi
 | `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) |
 | `crm` | Remove concepts from a session (mdel) | [docs/crm.md](docs/crm.md) |
+| `ctools-web` | Browser dashboard for all of the above | [Web dashboard](#web-dashboard) |
 
 Every tool takes `--version`. The session-mover tools (`ccopy`, `cextract`, `cconnect`, `crm`) also take `--verbose` for structured logging. Each tool's full flag reference, output formats, and examples live in its `docs/` page — the table above is just the 30-second version.
 
+## The problem
+
+You talk to LLMs all day. Over weeks, you build up a set of constraints, preferences, and goals. These live in your conversations as system messages. They are valuable. They are also trapped.
+
+Say you have been working with opencode for a month. You have refined your coding style through dozens of sessions. Now you start a new Claude Code project and you want those same preferences. You could copy them by hand. Or you could `cextract` them out and `cextract` them back in, or copy the whole conversation across with `ccopy`. Either way, your memory travels with you.
+
 ## How it works
 
 ctools is a substrate for moving memory between context windows. Cross-platform, agent-agnostic, designed like a bus.
@@ -97,6 +73,8 @@ Two stages: **extraction** and **filtering**.
 - A **strategy** extracts concepts from a conversation. It defines what counts as a concept and how to find it: regex patterns, LLM extraction, whatever. Different strategies produce different ontologies from the same conversation, because context is contestable.
 - A **filter** selects which extracted concepts reach a destination. It's a binary classifier: pass through or filter out. One concept list can fan out to many destinations, each with its own filter. A coding agent gets coding preferences, a security agent gets security constraints, a PM agent gets goals, all from the same source.
 
+A filter can be as simple as a type or substring match, or as smart as a **decision model** — a small local classifier that scores each concept and lets it through only when confident. Point a filter at a model and you get *semantic* filtering with no free text to parse: ask "is this concept about security?" and gate on the answer. The model is asked either through Ollama's typed `/v1/systemone` endpoint (calibrated probabilities, the home of decision-dedicated models) or through any OpenAI-compatible `/v1/chat/completions` server (portable, lettered decision-task prompt) — one `endpoint` field decides. See [cextract](docs/cextract.md) for the decision-model and JSON-RPC filter configs.
+
 ```mermaid
 graph LR
     SRC["source session"] --> STRAT["strategy<br/>(extraction)"]
@@ -109,13 +87,33 @@ graph LR
     FC --> DEST_C["destination C"]
 ```
 
-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 (JSON-RPC) protocol.
+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).
 
-## The problem
+## Write safety
 
-You talk to LLMs all day. Over weeks, you build up a set of constraints, preferences, and goals. These live in your conversations as system messages. They are valuable. They are also trapped.
+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.
 
-Say you have been working with opencode for a month. You have refined your coding style through dozens of sessions. Now you start a new Claude Code project and you want those same preferences. You could copy them by hand. Or you could `cextract` them out and `cextract` them back in, or copy the whole conversation across with `ccopy`. Either way, your memory travels with you.
+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
 
@@ -132,6 +130,12 @@ Say you have been working with opencode for a month. You have refined your codin
 | cline | JSON (`~/.cline/data/tasks/`) |
 | omp | JSONL (`~/.omp/agent/sessions/`, tree journal) |
 | freebuff | JSON (`~/.config/<codebuff>/projects/`) |
+| openclaw | SQLite (per-agent, `~/.openclaw/agents/`, `OPENCLAW_STATE_DIR`) |
+
+OpenClaw is a **personal assistant** rather than a terminal coding agent, so it
+runs in a local Gateway that owns its store; ctools reads and exports its
+sessions but does not seed new ones (the store has canonical-index and integrity
+checks that a raw insert cannot satisfy).
 
 Run `cdir` to see which endpoints are found on your system and where they store data.
 
@@ -157,23 +161,87 @@ 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
+web server (Python stdlib only, no web dependencies) with the same library
+underneath. Same on macOS, Windows, and Linux:
+
+```sh
+$ 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. 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 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
+```
+
 ## Installation
 
 ```sh
@@ -196,7 +264,7 @@ from ctools.lib import get_formatter
 from ctools.cgrep import grep_session
 from ctools.cextract import extract_concepts_from_messages
 from ctools.cdu import count_tokens, get_session_tokens
-from ctools.filterlib import JSONRPCFilter, load_filter
+from ctools.filterlib import JSONRPCFilter, SystemOneFilter, load_filter
 from ctools.log import configure_logging, get_logger
 ```
 
@@ -221,6 +289,13 @@ from ctools.agents import OpencodeAgent
 agent = OpencodeAgent('/backup/opencode')
 ```
 
+## Where to go next
+
+- **Per-tool reference** — the [Tools](#tools) table above links to a `docs/` page for each command: every flag, output format, and a worked example.
+- **The interchange format** — how a conversation becomes a portable, lossless envelope and back, and why 2N agents compose into N² transfers. See [interchange](docs/interchange.md).
+- **Filtering with decision models** — the full decision-model and JSON-RPC filter configs, with live examples. See [cextract](docs/cextract.md#filters) and [cconnect](docs/cconnect.md#filter-configuration).
+- **Adding an endpoint** — one `Agent` subclass plus a line in `AGENT_CLASSES`. See [Supported endpoints](#supported-endpoints).
+
 ## Credits
 
 ctools was extracted from [Gab n' Go](https://github.com/day50-dev/gabngo). It's named after [GNU mtools](https://www.gnu.org/software/mtools/), which does the same thing for DOS floppies — because your context window is about the size of a DOS-floppy. The flag habits are GNU's too: `--version`, `-1`, `-S`, `-u`, and the rest behave the way you'd expect.