@adaptiqai/mcp 0.1.5 → 0.1.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adaptiqai",
-  "version": "0.1.5",
-  "description": "AdaptiqAI's knowledge and memory tools in Claude Code: search, use and save your collections in the conversation you are in.",
+  "version": "0.1.6",
+  "description": "AdaptiqAI's knowledge and memory in Claude Code: search, use and save your collections in the conversation you are in, /adaptiq, and a note each turn of the collections it reads.",
   "author": {
     "name": "AdaptiqAI",
     "url": "https://adaptiqai.com"
@@ -14,5 +14,19 @@
       "command": "/bin/sh",
       "args": ["${CLAUDE_PLUGIN_ROOT}/bin/adaptiqai-mcp"]
     }
+  },
+  "commands": ["./claude-code/commands/adaptiq.md"],
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/sh \"${CLAUDE_PLUGIN_ROOT}/bin/adaptiqai-mcp\" hook claude-code",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
   }
 }

package/README.md

@@ -1,25 +1,40 @@
 # AdaptiqAI for Claude Code, Cline, Codex and any MCP app
 
 Your AdaptiqAI knowledge and this conversation's memory, as tools for the
-agent: an MCP server, over stdio, on the AdaptiqAI core.
+agent: an MCP server, over stdio, on the AdaptiqAI core. In Claude Code and
+Codex a prompt hook adds what a server can't: `/adaptiq`, and a note on each
+turn of the collections the conversation reads.
 
 ## Install
 
 **Claude Code**
 
+Install it as a Claude Code plugin from a marketplace that lists it (the
+package carries `.claude-plugin/plugin.json`): the plugin brings the server,
+`/adaptiq` and the prompt hook. Or add the server alone:
+
 ```bash
 claude mcp add adaptiqai -- npx -y @adaptiqai/mcp
 ```
 
-or install it as a Claude Code plugin from a marketplace that lists it (the
-package carries `.claude-plugin/plugin.json`). The plugin runs the server
-from the package with a Node.js 22 or newer: Claude Code itself needs none,
-and one started from the Dock often runs without a terminal's PATH, so
-`bin/adaptiqai-mcp` looks in PATH, then where Volta, fnm, asdf, mise,
-Homebrew and nvm put Node.js, or takes the one `ADAPTIQAI_NODE` names (in the
-`env` of Claude Code's settings). With none, the AdaptiqAI tools are missing
-and the agent is told why. The plugin starts it with `/bin/sh`, so on
-Windows add the server with `claude mcp add` as above.
+and the command and the hook as a plugin of their own, for one session or
+in the launcher that starts Claude Code (Connect to app's `adaptiq-claude`
+does this):
+
+```bash
+claude --plugin-dir "$(npm root -g)/@adaptiqai/mcp/claude-code"
+```
+
+`claude-code/` is a plugin with `/adaptiq` and the hook only, so a Claude Code
+that starts the server itself gets no second one. Both plugins run the server
+and the hook from the package with a Node.js 22 or newer: Claude Code itself
+needs none, and one started from the Dock often runs without a terminal's
+PATH, so `bin/adaptiqai-mcp` looks in PATH, then where Volta, fnm, asdf,
+mise, Homebrew and nvm put Node.js, or takes the one `ADAPTIQAI_NODE` names
+(in the `env` of Claude Code's settings). With none, the AdaptiqAI tools are
+missing and the agent is told why; the hook adds nothing and holds no prompt
+up. The plugins start it with `/bin/sh`, so on Windows add the server with
+`claude mcp add` as above.
 
 **Cline** (the CLI, 3.0.74)
 
@@ -36,63 +51,71 @@ That writes `~/.cline/data/settings/cline_mcp_settings.json`:
 **Codex** (0.166)
 
 Connect to app in the AdaptiqAI console sets it up in the `adaptiq` profile it
-writes (`codex --profile adaptiq`). By hand, add it to the profile that runs
-Codex on AdaptiqAI, not to `config.toml`: Codex tells the server nothing of
-where its model requests go, and on another provider the tools would act on
-a conversation the model never reads.
+writes (`$CODEX_HOME/adaptiq.config.toml`, `codex --profile adaptiq`). By
+hand, add it to the profile that runs Codex on AdaptiqAI:
 
 ```toml
 [mcp_servers.adaptiqai]
 command = "npx"
 args = ["-y", "@adaptiqai/mcp"]
-env_vars = ["CODEX_HOME"]
+env_vars = ["CODEX_HOME", "ADAPTIQAI_API_KEY"]
 
 [mcp_servers.adaptiqai.tools.adaptiq_knowledge]
 approval_mode = "approve"
 
 [mcp_servers.adaptiqai.tools.adaptiq_memory]
 approval_mode = "approve"
+
+[[hooks.UserPromptSubmit]]
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = "npx -y @adaptiqai/mcp hook codex"
+timeout = 30
 ```
 
 Codex offers an MCP server's tools in a `namespace` tool of the Responses
 API (`mcp__adaptiqai`), and asks before each call of a tool that does not say
 it only reads, unless `approval_mode` says otherwise; saving knowledge still
 asks. Codex passes a server only a few variables of its environment, so
-`CODEX_HOME`, where it keeps its conversations, is named.
+`CODEX_HOME`, where it keeps its conversations, is named. Codex runs a hook
+only once it is trusted: it asks at start, and `/hooks` shows it. The tools
+check that the thread runs on AdaptiqAI (below), so a server added elsewhere
+refuses rather than act on a conversation the model never reads.
 
 **Any other MCP app**: run `npx -y @adaptiqai/mcp` as a stdio server.
 
 ## Sign in
 
-The server signs in with the first of these it finds. The app's own key
-comes first: knowledge has to be in the workspace the app's model reads.
+The server signs in with the first of these that AdaptiqAI takes. The app's
+own key comes first: knowledge has to be in the workspace the app's model
+reads.
 
 - **Nothing to do when the app runs on an AdaptiqAI key the server can
   see.** Claude Code set up by the console (Connect to app's `adaptiq-claude`)
-  passes its environment on to the servers it starts, and the server uses the
-  key Claude Code runs on when `ANTHROPIC_BASE_URL` is AdaptiqAI's. Cline's
-  OpenRouter provider, pointed at AdaptiqAI, keeps its key in Cline's settings.
-  Codex hands a server no key of its own: Connect to app's profile starts the
-  server with the key Codex runs on as `ADAPTIQAI_API_KEY`.
+  passes its environment on to the servers and hooks it starts, and the
+  server uses the key Claude Code runs on when `ANTHROPIC_BASE_URL` is
+  AdaptiqAI's. Cline's OpenRouter provider, pointed at AdaptiqAI, keeps its
+  key in Cline's settings. Codex hands a server no key of its own: Connect to
+  app's profile starts the server, and the hook, with the key Codex runs on
+  as `ADAPTIQAI_API_KEY`.
 - **A key**: `ADAPTIQAI_API_KEY` in the server's environment.
-- **In the browser**: `npx -y @adaptiqai/mcp login`, or simply ask the agent
-  for your knowledge: while the computer is signed out, the first tool call
-  opens the approval page and tells the agent the code.
+- **In the browser**: `npx -y @adaptiqai/mcp login`, `/adaptiq signin`, or
+  simply ask the agent for your knowledge: while the computer is signed out,
+  the first tool call opens the approval page and tells the agent the code.
 
-One browser sign-in serves every app on this computer. It is kept in
-`~/.config/adaptiq/mcp/` (under `XDG_CONFIG_HOME` when set), readable by you
-alone.
-`npx -y @adaptiqai/mcp status` says whether this computer is signed in, and
-`logout` signs it out.
+A key AdaptiqAI refuses (revoked in the console) gives way to the next, and
+the last to the browser sign-in, so an old key never hides a working one or
+a sign-in made since. One browser sign-in serves every app on this computer.
+It is kept in `~/.config/adaptiq/mcp/` (under `XDG_CONFIG_HOME` when set),
+readable by you alone. `npx -y @adaptiqai/mcp status` says whether this
+computer is signed in, and `logout` signs it out.
 
 ## What it does
 
 - **`adaptiq_knowledge`**: what this conversation uses; find words, ids or
   names in the text of its collections, with the exact lines as
   document:line; search your saved knowledge by name; use or stop a
-  collection here. An MCP server has no hook into a turn, so it can't tell a
-  turn which collections the conversation reads, as the other plugins do; the
-  tool and the server's instructions lead with find instead.
+  collection here.
 - **`adaptiq_memory`**: how full the memory is; your saved collections; opens
   Knowledge in the browser to tidy up. It can't keep a conversation private,
   as the DeepSeek Harness and Pi plugins can: Claude Code, Cline and Codex
@@ -100,11 +123,88 @@ alone.
 - **`adaptiq_create_knowledge`**: save material (text, files, links) as a
   collection, only when you ask for it. The server checks the request
   against your own messages in the conversation, as every AdaptiqAI plugin
-  does.
+  does; a yes to the agent's offer to save counts, typed or (in Codex) given
+  through its question.
 
 Otherwise the tools, their words and their answers are the ones the DeepSeek
 Harness and Pi plugins have (`agentTools` in `@adaptiqai/core`).
 
+### `/adaptiq`
+
+In Claude Code type `/adaptiq` (the plugin lists it as `/adaptiqai:adaptiq`);
+Codex keeps `/` for its own commands and refuses one it doesn't know before
+any hook sees it, so there type `adaptiq` and the action. Codex 0.167 takes
+no commands of your own: custom prompts are gone, and a plugin's commands
+become `$` skills. The prompt hook answers it to you, and the prompt never
+reaches the model:
+
+| | |
+|---|---|
+| `/adaptiq` | workspace, this conversation, models and memory |
+| `/adaptiq knowledge` | knowledge used here, and the collections ready to use |
+| `/adaptiq use <name>` | use a collection, or an earlier conversation, here |
+| `/adaptiq stop <name>` | stop using it here (nothing is deleted) |
+| `/adaptiq open` | this conversation in AdaptiqAI Knowledge |
+| `/adaptiq diagnostics` | a report for support, without secrets |
+| `/adaptiq signin`, `signout` | connect this computer in the browser, or forget it |
+
+The words are the core's (`runCommand`), as in every AdaptiqAI plugin.
+`private` and `remember` say why they can't be had here. `adaptiqai-mcp
+command <action>` answers the same in a terminal, and from Codex's `!` in the
+thread it is run in.
+
+### What the hook adds to a turn
+
+Before a turn, the hook adds what the conversation doesn't hold yet, as
+additional context for that turn. Claude Code and Codex keep it in the
+conversation's transcript, which is how the hook knows it was said; after a
+compaction it is said again. What can't be had at once is left out, and the
+next turn asks again.
+
+- **The note**: which ready collections the conversation reads, and that find
+  looks them up: on the first turn, and again when they change (the core's
+  `turnNotes`). The tool and the server's instructions lead with find too.
+- **Look it up with find** (Codex): the instruction every AdaptiqAI plugin
+  gives the model (the core's `KNOWLEDGE_INSTRUCTIONS`). Codex hands the
+  server's instructions to the model provider only as the description of the
+  tools' namespace, so the hook adds it once to the thread as well. Claude
+  Code puts the server's instructions in the system prompt.
+- **Another model**: when a turn runs on another model than the one the
+  conversation last ran on, and AdaptiqAI keeps the conversation there, you
+  are told once, in the core's words, where its memory is, how to switch back
+  and how to start fresh: `AdaptiqAI: This conversation's memory is on
+  <model>. Switch back: /model <its id> · Start fresh on <this model>: /new`.
+  The model has it too. Codex says each turn's model; Claude Code's is read
+  from its transcript, where Claude Code 2.1.308 writes `/model` with the next
+  message, after the hook ran: the notice comes with the second message on
+  the new model. A conversation resumed in a Claude Code started on another
+  model gets it with the first.
+
+### Earlier conversations with @
+
+**Claude Code**: type `@` and the name of an earlier conversation: the
+server offers your saved conversations on the model Claude Code runs (the
+newest hundred, read as Claude Code starts it) as resources. Picking one
+makes this conversation read it from memory, as `/adaptiq use <name>` does:
+the prompt hook adds it, in the conversation the prompt is in, and says so to
+you and the model. The resource itself tells the model what you picked;
+reading it changes nothing, since a resource read doesn't say which
+conversation it is for. Claude Code reads a picked resource only in its
+interactive app (its print and SDK modes pass no resources), and the hook
+adds the conversation either way.
+
+**Codex** (0.167): type `@` and a word of an earlier Codex chat's title:
+Codex lists its own interactive chats there as tasks (not the ones
+`codex exec` ran), and writes the one picked into the prompt as a link to
+its thread. A Codex chat is the AdaptiqAI conversation of the same id, so the
+prompt hook makes this conversation read it from memory, as
+`adaptiq use <name>` does, and says so to you and the model. A chat AdaptiqAI
+doesn't keep on the model this turn runs on (one that ran on another model,
+or on another provider) is passed over in silence: Codex has the model read
+the chat itself (its `read_thread` tool). Codex's `@` lists no MCP
+resources, so a conversation from another app is added with
+`adaptiq use <name>`.
+
 ## Which conversation a call is in
 
 MCP has no conversation id, so the server reads each app where it keeps its
@@ -114,13 +214,15 @@ own:
 |---|---|---|---|
 | What the app hands the server | `CLAUDE_CODE_SESSION_ID`, `CLAUDE_PROJECT_DIR` and its own environment; `_meta["claudecode/toolUseId"]` on every call | nothing (no id in the environment or `_meta`) | `_meta.threadId` and `_meta.sessionId` on every call |
 | What its model requests name | `x-claude-code-session-id`, the same id | body `session_id`, only on its OpenRouter provider | body `client_metadata.thread_id`, the same thread |
-| How the server finds the call's conversation | the transcript (`~/.claude/projects/…/<id>.jsonl`) that holds the call's tool-use id: Claude Code keeps the server across `/clear` and `/resume`, so the starting id goes stale. An agent's call is in the agent's own transcript (`<id>/subagents/…/agent-<agent>.jsonl`), and is the session `<id>.<agent>`, as the gateway names an agent's requests; what an agent saves stays the chat's | the conversation whose messages file (`~/.cline/data/sessions/<id>/<id>.messages.json`) holds the call, not answered yet: Cline writes it there a few milliseconds before it makes it. Cline's hub runs every task in one process, so when two tasks make the same call at once, or no file holds it, the record started last before this server wins: Cline starts a server for each conversation | the thread `_meta.threadId` names: an agent the chat starts is a thread of its own, as its requests are; what an agent saves stays the chat's (`_meta.sessionId`). The chat's rollout (`$CODEX_HOME/sessions/<year>/<month>/<day>/rollout-<time>-<thread>.jsonl`, under the day the thread began) gives its folder and the person's messages |
-| What has to be true for it to reach the model | Claude Code on the AdaptiqAI gateway with `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` (the gateway names a chat only from `x-claude-code-request-class: main`) | Cline's OpenRouter provider with its base URL set to the AdaptiqAI gateway | Codex on the AdaptiqAI gateway with a key Connect to app made for Codex (the gateway names a thread only for one), and the server in that profile alone |
+| How the server finds the call's conversation | the transcript (`~/.claude/projects/…/<id>.jsonl`) that holds the call's tool-use id: Claude Code keeps the server across `/clear` and `/resume`, so the starting id goes stale, and a call no transcript holds is refused rather than put there. An agent's call is in the agent's own transcript (`<id>/subagents/…/agent-<agent>.jsonl`), and is the session `<id>.<agent>`, as the gateway names an agent's requests; what an agent saves stays the chat's | the conversation whose messages file (`~/.cline/data/sessions/<id>/<id>.messages.json`) holds the call, not answered yet: Cline writes it there a few milliseconds before it makes it. Cline's hub runs every task in one process, so when two tasks make the same call at once, or no file holds it, the record started last before this server wins: Cline starts a server for each conversation | the thread `_meta.threadId` names: an agent the chat starts is a thread of its own, as its requests are; what an agent saves stays the chat's (`_meta.sessionId`). The thread's rollout (`$CODEX_HOME/sessions/<year>/<month>/<day>/rollout-<time>-<thread>.jsonl`, under the day the thread began, which a UUIDv7 says; for another id the newest days are looked through) gives its folder, the person's messages and the model provider it runs on |
+| What has to be true for it to reach the model | Claude Code on the AdaptiqAI gateway with `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` (the gateway names a chat only from `x-claude-code-request-class: main`) | Cline's OpenRouter provider with its base URL set to the AdaptiqAI gateway | Codex on a model provider whose `base_url` is the AdaptiqAI gateway, in `config.toml` or a profile beside it, with a key Connect to app made for Codex (the gateway names a thread only for one) |
 
 When that is not so, every tool says why instead of attaching knowledge to a
-conversation the model never reads; Codex alone gives the server no sign of
-it, so there it rests on the profile. An app other than these three names no
-conversation, so its tool calls are refused the same way.
+conversation the model never reads; a Codex thread Codex keeps no rollout of
+(`codex exec --ephemeral`) can't be checked, so it is refused too. An app
+other than these three names no conversation, so its tool calls are refused
+the same way. The prompt hook gets the conversation's id from the app
+itself, and adds nothing to a conversation that does not reach AdaptiqAI.
 
 The transcript also holds your own messages, which `adaptiq_create_knowledge`
 checks its quote against. The server reads them on this computer, only when
@@ -131,11 +233,13 @@ nothing of them.
 
 | Variable | Default |
 |---|---|
-| `ADAPTIQAI_API_KEY` | none. Used when the app runs on no AdaptiqAI key the server can see; else the browser sign-in |
+| `ADAPTIQAI_API_KEY` | none. Used when the app runs on no AdaptiqAI key the server can see, or AdaptiqAI refuses that one; else the browser sign-in |
 | `ADAPTIQAI_API_BASE` | `https://api.adaptiqai.com` |
 | `ADAPTIQAI_CONSOLE_URL` | `https://memory.adaptiqai.com/memory` |
 | `ADAPTIQAI_NODE` | the plugin looks for a Node.js 22 or newer |
 
+The hook reads the same variables, from the app's environment.
+
 ## Development
 
 ```bash
@@ -143,10 +247,15 @@ pnpm install
 pnpm --filter @adaptiqai/mcp run build      # lib/index.js, one file with core bundled in
 pnpm --filter @adaptiqai/mcp run test
 claude mcp add adaptiqai-dev -- node "$PWD/packages/mcp/lib/index.js"
+claude --plugin-dir "$PWD/packages/mcp/claude-code"   # /adaptiq and the hook
+echo '{"session_id":"…","prompt":"/adaptiq"}' | node packages/mcp/lib/index.js hook claude-code
 ```
 
 MCP over stdio is a few JSON-RPC methods (`initialize`, `ping`,
 `tools/list`, `tools/call`), written by hand in `src/rpc.ts` and
 `src/index.ts`: the server ships as one file with no dependencies. Claude
 Code 2.1.308 asks for `server/discover` (MCP 2026-07-28) first and falls back
-to `initialize` when the server does not know it, as this one does not.
+to `initialize` when the server does not know it, as this one does not. The
+hook (`src/hook.ts`) reads the UserPromptSubmit input both apps send on stdin
+and answers with their JSON: Codex checks it against its own schema, so it
+gets only the fields Codex knows.

package/bin/adaptiqai-mcp

@@ -28,6 +28,12 @@ else
 fi
 
 reason='AdaptiqAI knowledge and memory are not available here: their MCP server needs Node.js 22 or newer on this computer, and the Claude Code plugin found none. When the person asks for AdaptiqAI knowledge or memory, tell them to install Node.js 22 or newer (nodejs.org), or to set ADAPTIQAI_NODE to one in the env of Claude Code'"'"'s settings, and then to start Claude Code again.'
+case ${1:-} in
+  # The prompt hook adds nothing, and never holds a prompt up: /adaptiq then
+  # reaches the agent as the command's own text, which says why.
+  hook) exit 0 ;;
+  ?*) echo "adaptiqai-mcp: Node.js 22 or newer is needed, and none was found. Install it from nodejs.org, or set ADAPTIQAI_NODE to one." >&2; exit 1 ;;
+esac
 echo "adaptiqai-mcp: $reason" >&2
 while IFS= read -r line || [ -n "$line" ]; do
   id=$(printf '%s\n' "$line" | sed -nE 's/.*"id":("[^"]*"|-?[0-9]+).*/\1/p')

package/claude-code/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "adaptiqai",
+  "description": "AdaptiqAI's /adaptiq command and prompt hook in Claude Code, for a Claude Code that starts AdaptiqAI's MCP server itself (adaptiq-claude): the plugin at the package's root brings the server too.",
+  "author": {
+    "name": "AdaptiqAI",
+    "url": "https://adaptiqai.com"
+  },
+  "homepage": "https://adaptiqai.com",
+  "license": "UNLICENSED"
+}

package/claude-code/commands/adaptiq.md

@@ -0,0 +1,6 @@
+---
+description: AdaptiqAI here — status, knowledge, use or stop a collection, open, diagnostics, sign in or out
+argument-hint: "[status | knowledge | use <name> | stop <name> | open | diagnostics | signin | signout]"
+disable-model-invocation: true
+---
+The person typed /adaptiq $ARGUMENTS, AdaptiqAI's command. AdaptiqAI's prompt hook answers it before it reaches you, but the hook did not run here: it needs Node.js 22 or newer on this computer. Tell the person that in one sentence, and that they can install Node.js 22 or newer (nodejs.org), or set ADAPTIQAI_NODE to one in the env of Claude Code's settings, and then start Claude Code again. Do nothing else for this message.

package/claude-code/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/sh \"${CLAUDE_PLUGIN_ROOT}/../bin/adaptiqai-mcp\" hook claude-code",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}