ctxttools 0.1.7__tar.gz → 0.2.1__tar.gz

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.
Files changed (31) hide show
  1. ctxttools-0.2.1/PKG-INFO +243 -0
  2. ctxttools-0.2.1/README.md +226 -0
  3. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/agents.py +1148 -8
  4. ctxttools-0.2.1/ctools/ccat.py +233 -0
  5. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/cconnect.py +1 -1
  6. ctxttools-0.2.1/ctools/ccopy.py +478 -0
  7. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/cdir.py +120 -39
  8. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/cdu.py +15 -5
  9. ctxttools-0.1.7/ctools/ccopy.py → ctxttools-0.2.1/ctools/cextract.py +27 -21
  10. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/cgrep.py +83 -25
  11. ctxttools-0.2.1/ctools/cli.py +190 -0
  12. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/crm.py +1 -1
  13. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/ctools_mcp.py +1 -1
  14. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/lib.py +2 -0
  15. ctxttools-0.2.1/ctxttools.egg-info/PKG-INFO +243 -0
  16. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctxttools.egg-info/SOURCES.txt +2 -0
  17. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctxttools.egg-info/entry_points.txt +2 -0
  18. {ctxttools-0.1.7 → ctxttools-0.2.1}/pyproject.toml +3 -1
  19. ctxttools-0.1.7/PKG-INFO +0 -594
  20. ctxttools-0.1.7/README.md +0 -577
  21. ctxttools-0.1.7/ctools/cli.py +0 -83
  22. ctxttools-0.1.7/ctxttools.egg-info/PKG-INFO +0 -594
  23. {ctxttools-0.1.7 → ctxttools-0.2.1}/LICENSE.MIT +0 -0
  24. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/__init__.py +0 -0
  25. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/filterlib.py +0 -0
  26. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/log.py +0 -0
  27. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctools/strategy.py +0 -0
  28. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctxttools.egg-info/dependency_links.txt +0 -0
  29. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctxttools.egg-info/requires.txt +0 -0
  30. {ctxttools-0.1.7 → ctxttools-0.2.1}/ctxttools.egg-info/top_level.txt +0 -0
  31. {ctxttools-0.1.7 → ctxttools-0.2.1}/setup.cfg +0 -0
@@ -0,0 +1,243 @@
1
+ Metadata-Version: 2.4
2
+ Name: ctxttools
3
+ Version: 0.2.1
4
+ Summary: CLI tools for LLM conversations
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ License-File: LICENSE.MIT
8
+ Requires-Dist: typer>=0.9.0
9
+ Requires-Dist: rich>=13.0.0
10
+ Requires-Dist: tiktoken>=0.5.0
11
+ Requires-Dist: structlog>=24.0
12
+ Provides-Extra: mcp
13
+ Requires-Dist: mcp>=1.2.0; extra == "mcp"
14
+ Provides-Extra: dev
15
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
16
+ Dynamic: license-file
17
+
18
+ <p align="center">
19
+ <img width="500" alt="ctools" src="https://github.com/user-attachments/assets/ee781bbe-6364-44ed-be2d-72114f1e6d8a" /><br/>
20
+ <a href=https://pypi.org/project/ctxttools><img src=https://badge.fury.io/py/ctxttools.svg/></a>
21
+ <br/><br/><b>Try it now</b><br/>
22
+ <code>uvx --from ctxttools cdir</code>
23
+ <br/><br/><b>Then install it</b><br/>
24
+ <code>uv tool install ctxttools</code>
25
+ </p>
26
+
27
+ ------
28
+ **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.
29
+
30
+ 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).
31
+
32
+ Here's an example:
33
+
34
+ > I look for mentions of snake game in opencode using cgrep
35
+ <pre>
36
+ $ <b>cgrep</b> "snake game" opencode
37
+ opencode/ses_a1d1a5a4df984ee698cab4a7:1:user: make a simple snake game in python
38
+ opencode/ses_a1d1a5a4df984ee698cab4a7:2:assistant: I'll make a terminal-based snake game using `curses` (standard library, no dependencies).
39
+ opencode/ses_a1d1a5a4df984ee698cab4a7:3:assistant: Done — `snake.py` is a terminal snake game using Python's built-in `curses` module (no dependencies).
40
+ </pre>
41
+
42
+ > cool let's look at the status of that session using cdir
43
+ <pre>
44
+ $ <b>cdir</b> -l opencode/ses_a1d1a5a4df984ee698cab4a7
45
+ ID NAME MODIFIED SIZE MSGS PATH
46
+ ses_a1d1a5a4df984ee698cab4a7 make a simple snake game in python 2026-10-07 16:56 2.7 KB 3 /home/chris/.local/share/opencode
47
+
48
+ 1 session(s)
49
+ </pre>
50
+
51
+ > Alright let's copy that session from opencode into pi!
52
+ <pre>
53
+ $ <b>ccopy</b> opencode/ses_a1d1a5a4df984ee698cab4a7 pi
54
+ Copied 3 message(s) from opencode/ses_a1d1a5a4df984ee698cab4a7 to a new pi session: e357f435-f813-463a-b313-f97f1051f3cb
55
+ Resume it with:
56
+ pi --session e357f435-f813-463a-b313-f97f1051f3cb
57
+ </pre>
58
+
59
+ As you can see, these are unix-friendly tools using simple paradigms that you are already familiar with.
60
+
61
+ ----
62
+
63
+ ### 1. `cgrep` — find it in your past conversations
64
+
65
+ 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:
66
+
67
+ ```shell
68
+ $ cgrep -i "ssl"
69
+ claude-code/a351eedf:142:assistant: … the TLS handshake fails with SSL wrong version number …
70
+ opencode/ses_000d460f:16:user: ok graflex has an erorr in the check. i see this: … [[SSL: WRONG_VERSION_NUMBER] …
71
+ opencode/ses_000d460f:34:assistant: Found it. Root cause: `_check_host` (graflex/__init__.py:128) tries `http`, and …
72
+ ```
73
+
74
+ 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.
75
+
76
+ ### 2. `ccopy` — move your project from one tool to another
77
+
78
+ 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:
79
+
80
+ ```shell
81
+ $ ccopy opencode/ses_abc123 claude-code
82
+ Copied 128 message(s) from opencode/ses_abc123 to a new claude-code session: 1a2b3c
83
+ Resume it with:
84
+ claude-code --resume 1a2b3c
85
+ ```
86
+
87
+ 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).
88
+
89
+ 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.
90
+
91
+ **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).
92
+
93
+ ## Tools
94
+
95
+ | Tool | What it does | Docs |
96
+ |------|--------------|------|
97
+ | `cgrep` | Search conversation content (grep across every agent) | [docs/cgrep.md](docs/cgrep.md) |
98
+ | `cdir` | List sessions (ls for your history) | [docs/cdir.md](docs/cdir.md) |
99
+ | `ccat` | Print one or more conversations (cat for your history) | [docs/ccat.md](docs/ccat.md) |
100
+ | `ccopy` | Copy a whole conversation from one agent to a new session in another | [docs/ccopy.md](docs/ccopy.md) |
101
+ | `cextract` | Extract concepts from a session into files, and inject them back | [docs/cextract.md](docs/cextract.md) |
102
+ | `cconnect` | Live concept pipelines between sessions | [docs/cconnect.md](docs/cconnect.md) |
103
+ | `cdu` | Token usage per session (du for context windows) | [docs/cdu.md](docs/cdu.md) |
104
+ | `crm` | Remove concepts from a session (mdel) | [docs/crm.md](docs/crm.md) |
105
+
106
+ 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.
107
+
108
+ ## How it works
109
+
110
+ ctools is a substrate for moving memory between context windows. Cross-platform, agent-agnostic, designed like a bus.
111
+
112
+ Two stages: **extraction** and **filtering**.
113
+
114
+ - 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.
115
+ - 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.
116
+
117
+ ```mermaid
118
+ graph LR
119
+ SRC["source session"] --> STRAT["strategy<br/>(extraction)"]
120
+ STRAT --> CONCEPTS["concept list"]
121
+ CONCEPTS --> FA["filter A"]
122
+ CONCEPTS --> FB["filter B"]
123
+ CONCEPTS --> FC["filter C"]
124
+ FA --> DEST_A["destination A"]
125
+ FB --> DEST_B["destination B"]
126
+ FC --> DEST_C["destination C"]
127
+ ```
128
+
129
+ 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.
130
+
131
+ ## The problem
132
+
133
+ 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.
134
+
135
+ 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.
136
+
137
+ ## Supported endpoints
138
+
139
+ | Agent | Storage |
140
+ |-------|---------|
141
+ | claude | JSON |
142
+ | claude-code | JSONL |
143
+ | opencode | SQLite |
144
+ | kilo | SQLite (opencode fork, same schema) |
145
+ | codex | JSONL |
146
+ | pi | JSONL |
147
+ | goose | SQLite |
148
+ | hermes | SQLite (`~/.hermes/state.db`, `$HERMES_HOME`) |
149
+ | cline | JSON (`~/.cline/data/tasks/`) |
150
+ | omp | JSONL (`~/.omp/agent/sessions/`, tree journal) |
151
+ | freebuff | JSON (`~/.config/<codebuff>/projects/`) |
152
+
153
+ Run `cdir` to see which endpoints are found on your system and where they store data.
154
+
155
+ Every endpoint is one class in `ctools/agents.py`. The base `Agent` defines the whole interface the tools use — `sessions()`, `messages()`, `raw_messages()`, `lines()`, `inject_system()`, `inject_toolcall()`, `remove_messages()`, `create_session()` — and the storage-shaped subclasses (`JsonAgent`, `JsonlAgent`, `SqliteAgent`) implement most of it. Adding an endpoint means writing one subclass and adding it to `AGENT_CLASSES`; no command changes.
156
+
157
+ ```python
158
+ from ctools.agents import JsonlAgent, Session
159
+
160
+ class MyAgent(JsonlAgent):
161
+ name = 'myagent'
162
+ description = 'My Coding Agent'
163
+ session_pattern = 'sessions/**/*.jsonl'
164
+
165
+ @classmethod
166
+ def default_base_path(cls):
167
+ return Path.home() / '.myagent'
168
+
169
+ def sessions(self):
170
+ ...
171
+ ```
172
+
173
+ Anything the storage cannot do — pi's session trees cannot be rewritten in place — raises `UnsupportedOperation` instead of being silently skipped.
174
+
175
+ ## MCP server
176
+
177
+ There is an MCP server for use from Claude, opencode, Cursor, or anything else that speaks MCP.
178
+
179
+ Tools: `list_agents`, `list_sessions`, `search_sessions`, `export_session`, `extract_concepts`, `copy_concepts`, `get_session_concepts`.
180
+
181
+ Add to your MCP config:
182
+
183
+ ```json
184
+ {
185
+ "mcpServers": {
186
+ "ctools": {
187
+ "command": "python",
188
+ "args": ["/ABSOLUTE/PATH/TO/ctools/ctools_mcp.py"]
189
+ }
190
+ }
191
+ }
192
+ ```
193
+
194
+ ## Installation
195
+
196
+ ```sh
197
+ pip install ctxttools
198
+ ```
199
+
200
+ For MCP server support:
201
+
202
+ ```sh
203
+ pip install ctxttools[mcp]
204
+ ```
205
+
206
+ ## Library
207
+
208
+ Works as a Python library too.
209
+
210
+ ```python
211
+ from ctools.agents import REGISTRY, OpencodeAgent, SessionNotFound
212
+ from ctools.lib import get_formatter
213
+ from ctools.cgrep import grep_session
214
+ from ctools.cextract import extract_concepts_from_messages
215
+ from ctools.cdu import count_tokens, get_session_tokens
216
+ from ctools.filterlib import JSONRPCFilter, load_filter
217
+ from ctools.log import configure_logging, get_logger
218
+ ```
219
+
220
+ Everything goes through an agent:
221
+
222
+ ```python
223
+ from ctools.agents import REGISTRY
224
+
225
+ agent = REGISTRY['opencode']
226
+ for session in agent.sessions():
227
+ print(session.id, session.name, session.size)
228
+
229
+ for message in agent.messages('ses_abc123'):
230
+ print(message.role, message.content)
231
+ ```
232
+
233
+ Point an agent somewhere else by constructing it with a path:
234
+
235
+ ```python
236
+ from ctools.agents import OpencodeAgent
237
+
238
+ agent = OpencodeAgent('/backup/opencode')
239
+ ```
240
+
241
+ ## Credits
242
+
243
+ 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.
@@ -0,0 +1,226 @@
1
+ <p align="center">
2
+ <img width="500" alt="ctools" src="https://github.com/user-attachments/assets/ee781bbe-6364-44ed-be2d-72114f1e6d8a" /><br/>
3
+ <a href=https://pypi.org/project/ctxttools><img src=https://badge.fury.io/py/ctxttools.svg/></a>
4
+ <br/><br/><b>Try it now</b><br/>
5
+ <code>uvx --from ctxttools cdir</code>
6
+ <br/><br/><b>Then install it</b><br/>
7
+ <code>uv tool install ctxttools</code>
8
+ </p>
9
+
10
+ ------
11
+ **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.
12
+
13
+ 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).
14
+
15
+ Here's an example:
16
+
17
+ > I look for mentions of snake game in opencode using cgrep
18
+ <pre>
19
+ $ <b>cgrep</b> "snake game" opencode
20
+ opencode/ses_a1d1a5a4df984ee698cab4a7:1:user: make a simple snake game in python
21
+ opencode/ses_a1d1a5a4df984ee698cab4a7:2:assistant: I'll make a terminal-based snake game using `curses` (standard library, no dependencies).
22
+ opencode/ses_a1d1a5a4df984ee698cab4a7:3:assistant: Done — `snake.py` is a terminal snake game using Python's built-in `curses` module (no dependencies).
23
+ </pre>
24
+
25
+ > cool let's look at the status of that session using cdir
26
+ <pre>
27
+ $ <b>cdir</b> -l opencode/ses_a1d1a5a4df984ee698cab4a7
28
+ ID NAME MODIFIED SIZE MSGS PATH
29
+ ses_a1d1a5a4df984ee698cab4a7 make a simple snake game in python 2026-10-07 16:56 2.7 KB 3 /home/chris/.local/share/opencode
30
+
31
+ 1 session(s)
32
+ </pre>
33
+
34
+ > Alright let's copy that session from opencode into pi!
35
+ <pre>
36
+ $ <b>ccopy</b> opencode/ses_a1d1a5a4df984ee698cab4a7 pi
37
+ Copied 3 message(s) from opencode/ses_a1d1a5a4df984ee698cab4a7 to a new pi session: e357f435-f813-463a-b313-f97f1051f3cb
38
+ Resume it with:
39
+ pi --session e357f435-f813-463a-b313-f97f1051f3cb
40
+ </pre>
41
+
42
+ As you can see, these are unix-friendly tools using simple paradigms that you are already familiar with.
43
+
44
+ ----
45
+
46
+ ### 1. `cgrep` — find it in your past conversations
47
+
48
+ 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:
49
+
50
+ ```shell
51
+ $ cgrep -i "ssl"
52
+ claude-code/a351eedf:142:assistant: … the TLS handshake fails with SSL wrong version number …
53
+ opencode/ses_000d460f:16:user: ok graflex has an erorr in the check. i see this: … [[SSL: WRONG_VERSION_NUMBER] …
54
+ opencode/ses_000d460f:34:assistant: Found it. Root cause: `_check_host` (graflex/__init__.py:128) tries `http`, and …
55
+ ```
56
+
57
+ 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.
58
+
59
+ ### 2. `ccopy` — move your project from one tool to another
60
+
61
+ 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:
62
+
63
+ ```shell
64
+ $ ccopy opencode/ses_abc123 claude-code
65
+ Copied 128 message(s) from opencode/ses_abc123 to a new claude-code session: 1a2b3c
66
+ Resume it with:
67
+ claude-code --resume 1a2b3c
68
+ ```
69
+
70
+ 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).
71
+
72
+ 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.
73
+
74
+ **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).
75
+
76
+ ## Tools
77
+
78
+ | Tool | What it does | Docs |
79
+ |------|--------------|------|
80
+ | `cgrep` | Search conversation content (grep across every agent) | [docs/cgrep.md](docs/cgrep.md) |
81
+ | `cdir` | List sessions (ls for your history) | [docs/cdir.md](docs/cdir.md) |
82
+ | `ccat` | Print one or more conversations (cat for your history) | [docs/ccat.md](docs/ccat.md) |
83
+ | `ccopy` | Copy a whole conversation from one agent to a new session in another | [docs/ccopy.md](docs/ccopy.md) |
84
+ | `cextract` | Extract concepts from a session into files, and inject them back | [docs/cextract.md](docs/cextract.md) |
85
+ | `cconnect` | Live concept pipelines between sessions | [docs/cconnect.md](docs/cconnect.md) |
86
+ | `cdu` | Token usage per session (du for context windows) | [docs/cdu.md](docs/cdu.md) |
87
+ | `crm` | Remove concepts from a session (mdel) | [docs/crm.md](docs/crm.md) |
88
+
89
+ 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.
90
+
91
+ ## How it works
92
+
93
+ ctools is a substrate for moving memory between context windows. Cross-platform, agent-agnostic, designed like a bus.
94
+
95
+ Two stages: **extraction** and **filtering**.
96
+
97
+ - 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.
98
+ - 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.
99
+
100
+ ```mermaid
101
+ graph LR
102
+ SRC["source session"] --> STRAT["strategy<br/>(extraction)"]
103
+ STRAT --> CONCEPTS["concept list"]
104
+ CONCEPTS --> FA["filter A"]
105
+ CONCEPTS --> FB["filter B"]
106
+ CONCEPTS --> FC["filter C"]
107
+ FA --> DEST_A["destination A"]
108
+ FB --> DEST_B["destination B"]
109
+ FC --> DEST_C["destination C"]
110
+ ```
111
+
112
+ 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.
113
+
114
+ ## The problem
115
+
116
+ 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.
117
+
118
+ 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.
119
+
120
+ ## Supported endpoints
121
+
122
+ | Agent | Storage |
123
+ |-------|---------|
124
+ | claude | JSON |
125
+ | claude-code | JSONL |
126
+ | opencode | SQLite |
127
+ | kilo | SQLite (opencode fork, same schema) |
128
+ | codex | JSONL |
129
+ | pi | JSONL |
130
+ | goose | SQLite |
131
+ | hermes | SQLite (`~/.hermes/state.db`, `$HERMES_HOME`) |
132
+ | cline | JSON (`~/.cline/data/tasks/`) |
133
+ | omp | JSONL (`~/.omp/agent/sessions/`, tree journal) |
134
+ | freebuff | JSON (`~/.config/<codebuff>/projects/`) |
135
+
136
+ Run `cdir` to see which endpoints are found on your system and where they store data.
137
+
138
+ Every endpoint is one class in `ctools/agents.py`. The base `Agent` defines the whole interface the tools use — `sessions()`, `messages()`, `raw_messages()`, `lines()`, `inject_system()`, `inject_toolcall()`, `remove_messages()`, `create_session()` — and the storage-shaped subclasses (`JsonAgent`, `JsonlAgent`, `SqliteAgent`) implement most of it. Adding an endpoint means writing one subclass and adding it to `AGENT_CLASSES`; no command changes.
139
+
140
+ ```python
141
+ from ctools.agents import JsonlAgent, Session
142
+
143
+ class MyAgent(JsonlAgent):
144
+ name = 'myagent'
145
+ description = 'My Coding Agent'
146
+ session_pattern = 'sessions/**/*.jsonl'
147
+
148
+ @classmethod
149
+ def default_base_path(cls):
150
+ return Path.home() / '.myagent'
151
+
152
+ def sessions(self):
153
+ ...
154
+ ```
155
+
156
+ Anything the storage cannot do — pi's session trees cannot be rewritten in place — raises `UnsupportedOperation` instead of being silently skipped.
157
+
158
+ ## MCP server
159
+
160
+ There is an MCP server for use from Claude, opencode, Cursor, or anything else that speaks MCP.
161
+
162
+ Tools: `list_agents`, `list_sessions`, `search_sessions`, `export_session`, `extract_concepts`, `copy_concepts`, `get_session_concepts`.
163
+
164
+ Add to your MCP config:
165
+
166
+ ```json
167
+ {
168
+ "mcpServers": {
169
+ "ctools": {
170
+ "command": "python",
171
+ "args": ["/ABSOLUTE/PATH/TO/ctools/ctools_mcp.py"]
172
+ }
173
+ }
174
+ }
175
+ ```
176
+
177
+ ## Installation
178
+
179
+ ```sh
180
+ pip install ctxttools
181
+ ```
182
+
183
+ For MCP server support:
184
+
185
+ ```sh
186
+ pip install ctxttools[mcp]
187
+ ```
188
+
189
+ ## Library
190
+
191
+ Works as a Python library too.
192
+
193
+ ```python
194
+ from ctools.agents import REGISTRY, OpencodeAgent, SessionNotFound
195
+ from ctools.lib import get_formatter
196
+ from ctools.cgrep import grep_session
197
+ from ctools.cextract import extract_concepts_from_messages
198
+ from ctools.cdu import count_tokens, get_session_tokens
199
+ from ctools.filterlib import JSONRPCFilter, load_filter
200
+ from ctools.log import configure_logging, get_logger
201
+ ```
202
+
203
+ Everything goes through an agent:
204
+
205
+ ```python
206
+ from ctools.agents import REGISTRY
207
+
208
+ agent = REGISTRY['opencode']
209
+ for session in agent.sessions():
210
+ print(session.id, session.name, session.size)
211
+
212
+ for message in agent.messages('ses_abc123'):
213
+ print(message.role, message.content)
214
+ ```
215
+
216
+ Point an agent somewhere else by constructing it with a path:
217
+
218
+ ```python
219
+ from ctools.agents import OpencodeAgent
220
+
221
+ agent = OpencodeAgent('/backup/opencode')
222
+ ```
223
+
224
+ ## Credits
225
+
226
+ 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.