realontext 0.10.0 → 0.12.0
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.
- package/.claude-plugin/plugin.json +1 -1
- package/LICENSE +1 -1
- package/README.md +12 -1
- package/bin/realontext.js +9 -6
- package/hooks/hint.js +5 -0
- package/hooks/hint.md +3 -0
- package/hooks/hooks.json +16 -0
- package/lib/agents.js +194 -0
- package/lib/binary.js +1 -16
- package/lib/hook.js +39 -0
- package/lib/mcp.js +0 -1
- package/lib/rules.md +3 -0
- package/lib/setup.js +63 -62
- package/lib/update.js +0 -6
- package/package.json +16 -6
- package/pi/realontext.js +83 -0
package/LICENSE
CHANGED
|
@@ -16,7 +16,7 @@ Copyright (C) 2026 FlowerRealm. All rights reserved.
|
|
|
16
16
|
适用性和非侵权的担保。在任何情况下,作者或版权持有人均不对任何索赔、损害或其
|
|
17
17
|
他责任负责。
|
|
18
18
|
|
|
19
|
-
第三方依赖各自适用其自身的许可证,见 vcpkg.json 所列各项目。其中 libgit2 为
|
|
19
|
+
第三方依赖各自适用其自身的许可证,见 client/vcpkg.json 所列各项目。其中 libgit2 为
|
|
20
20
|
GPL-2.0,附带 linking exception,链接不构成传染,因此不限制本许可的选择。其余
|
|
21
21
|
依赖为 MIT、Apache-2.0、CC0、curl 许可或公有领域,均允许在专有软件中使用。
|
|
22
22
|
|
package/README.md
CHANGED
|
@@ -73,7 +73,18 @@ turns this off.
|
|
|
73
73
|
## From the shell
|
|
74
74
|
|
|
75
75
|
```bash
|
|
76
|
-
|
|
76
|
+
realontext query -i --pattern 'yaml|load' # the current directory
|
|
77
|
+
realontext query --pattern 'yaml|load' --query "why does loading yaml crash" # described: the Relay ranks
|
|
78
|
+
realontext query --pattern 'yaml|load' --path src --path lib -g '*.rs' # paths, and rg's options
|
|
79
|
+
git log --oneline | realontext query --pattern fix # stdin, line by line
|
|
80
|
+
cat loader.rs | realontext query --label loader.rs --pattern yaml # stdin, named for its grammar
|
|
77
81
|
```
|
|
78
82
|
|
|
83
|
+
The regex is `--pattern`, the description `--query`, each place to search
|
|
84
|
+
`--path`; every other word goes to ripgrep as one of its options. Code comes back as
|
|
85
|
+
whole functions and classes, any other file line by line. With `--query`, a
|
|
86
|
+
description of the code, the Relay ranks the results; without it, the
|
|
87
|
+
pattern's words do. As with grep: text on stdout (`--json` for programs), exit
|
|
88
|
+
status 0 with results, 1 without, 2 on error.
|
|
89
|
+
|
|
79
90
|
Builds: macOS on Apple Silicon (13 and later), x64 Linux and x64 Windows.
|
package/bin/realontext.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// The `realontext` command npm installs: runs the binary of this platform with
|
|
3
3
|
// this process's arguments, stdio and exit status (D39). What is written here
|
|
4
|
-
// instead is what Node does better: `setup` edits agents' configs (D74),
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
//
|
|
4
|
+
// instead is what Node does better: `setup` edits agents' configs (D74),
|
|
5
|
+
// `hook` answers the hooks it wrote (D107), and with no command, in a
|
|
6
|
+
// terminal, a menu of everything (D75). Each start may update the binary in
|
|
7
|
+
// the background (D94); `mcp` passes the session through and switches to a
|
|
8
|
+
// newer binary in its middle (D95).
|
|
8
9
|
"use strict";
|
|
9
10
|
|
|
10
11
|
const { spawnSync } = require("child_process");
|
|
@@ -12,7 +13,7 @@ const { spawnSync } = require("child_process");
|
|
|
12
13
|
const [command, ...rest] = process.argv.slice(2);
|
|
13
14
|
const terminal = process.stdin.isTTY && process.stdout.isTTY;
|
|
14
15
|
|
|
15
|
-
if (command !== "mcp") require("../lib/update.js").start();
|
|
16
|
+
if (command !== "mcp" && command !== "hook") require("../lib/update.js").start();
|
|
16
17
|
|
|
17
18
|
function exit(status) {
|
|
18
19
|
if (typeof status === "string") process.kill(process.pid, status);
|
|
@@ -25,6 +26,8 @@ if (terminal && (command === undefined || (command === "setup" && rest.length ==
|
|
|
25
26
|
.then((status) => process.exit(status));
|
|
26
27
|
} else if (command === "setup") {
|
|
27
28
|
process.exit(require("../lib/setup.js").setup(rest));
|
|
29
|
+
} else if (command === "hook") {
|
|
30
|
+
require("../lib/hook.js")(rest[0]);
|
|
28
31
|
} else {
|
|
29
32
|
const binary = require("../lib/binary.js");
|
|
30
33
|
let path;
|
|
@@ -37,7 +40,7 @@ if (terminal && (command === undefined || (command === "setup" && rest.length ==
|
|
|
37
40
|
if (command === "mcp") {
|
|
38
41
|
require("../lib/mcp.js")(path, rest).then(exit);
|
|
39
42
|
} else {
|
|
40
|
-
const run = spawnSync(path, process.argv.slice(2), { stdio: "inherit"
|
|
43
|
+
const run = spawnSync(path, process.argv.slice(2), { stdio: "inherit" });
|
|
41
44
|
if (run.error) {
|
|
42
45
|
console.error(`realontext: ${run.error.message}`);
|
|
43
46
|
process.exit(1);
|
package/hooks/hint.js
ADDED
package/hooks/hint.md
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
<realontext>
|
|
2
|
+
To search source code, call codebase-retrieval instead of grep or rg: it returns whole functions ranked by what you ask, with line numbers. `pattern` is the regex you would grep for; add `query`, an English description of the code, when you are describing behavior, and leave it out for a name you know. For docs, configs, logs and a command's output, use `realontext query --pattern RE [--path PATH]...` in the shell, or pipe into it: `git log | realontext query --pattern fix`. Do not run grep or rg at all.
|
|
3
|
+
</realontext>
|
package/hooks/hooks.json
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "Reminds the agent of codebase-retrieval, once a session",
|
|
3
|
+
"hooks": {
|
|
4
|
+
"PreToolUse": [
|
|
5
|
+
{
|
|
6
|
+
"matcher": "Bash|Grep",
|
|
7
|
+
"hooks": [
|
|
8
|
+
{
|
|
9
|
+
"type": "command",
|
|
10
|
+
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hint.js\""
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
}
|
|
14
|
+
]
|
|
15
|
+
}
|
|
16
|
+
}
|
package/lib/agents.js
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
// How realontext is connected to each agent (D107), the data `setup.js` acts
|
|
2
|
+
// on and `hook.js` answers from. An agent is a list of steps, each one of:
|
|
3
|
+
//
|
|
4
|
+
// run a command of the agent's own CLI; `clear` first, quietly, when
|
|
5
|
+
// its `add` refuses a name it already has
|
|
6
|
+
// json `value` set at the key path `at` of a JSON file
|
|
7
|
+
// list `value` put in the array at `at` of a JSON file, in place of the
|
|
8
|
+
// entries an earlier setup put there
|
|
9
|
+
// block `text` as a marked block at the end of a text file (TOML, YAML,
|
|
10
|
+
// Markdown), in place of the block an earlier setup put there
|
|
11
|
+
// file `text` as the whole of a file of realontext's own
|
|
12
|
+
//
|
|
13
|
+
// A path starting with `~/` is under the home directory, a relative one under
|
|
14
|
+
// the directory `setup` runs in. Three things go in: the MCP server, everywhere;
|
|
15
|
+
// the once-a-session reminder (D106), where the agent has a hook that adds
|
|
16
|
+
// context the model sees; the usage rules, where the agent is known not to
|
|
17
|
+
// pass the server's instructions to the model. `hook` names the event the
|
|
18
|
+
// reminder answers and, with `flat`, that the answer is not wrapped in
|
|
19
|
+
// `hookSpecificOutput`.
|
|
20
|
+
"use strict";
|
|
21
|
+
|
|
22
|
+
const fs = require("fs");
|
|
23
|
+
const os = require("os");
|
|
24
|
+
const path = require("path");
|
|
25
|
+
|
|
26
|
+
const SERVER = { command: "realontext", args: ["mcp"] };
|
|
27
|
+
const RULES = fs.readFileSync(path.join(__dirname, "rules.md"), "utf8");
|
|
28
|
+
// Absolute: dsh reads the hooks file's path from YAML as it is.
|
|
29
|
+
const DSH = process.env.DSH_HOME || path.join(os.homedir(), ".dsh");
|
|
30
|
+
|
|
31
|
+
const hook = (agent) => `realontext hook ${agent}`;
|
|
32
|
+
// The Claude Code shape, that Gemini CLI, Qwen Code, Codex and dsh read too.
|
|
33
|
+
const nested = (agent, matcher) => ({ ...(matcher && { matcher }), hooks: [{ type: "command", command: hook(agent) }] });
|
|
34
|
+
// The Copilot shape: no matcher, no nesting.
|
|
35
|
+
const flat = (agent) => ({ type: "command", command: hook(agent) });
|
|
36
|
+
|
|
37
|
+
const agents = {
|
|
38
|
+
claude: {
|
|
39
|
+
name: "Claude Code",
|
|
40
|
+
steps: [
|
|
41
|
+
{ clear: "claude mcp remove realontext -s local", run: "claude mcp add realontext -- realontext mcp" },
|
|
42
|
+
{ list: ".claude/settings.local.json", at: ["hooks", "PreToolUse"], value: nested("claude", "Bash|Grep") },
|
|
43
|
+
],
|
|
44
|
+
hook: { event: "PreToolUse" },
|
|
45
|
+
},
|
|
46
|
+
codex: {
|
|
47
|
+
name: "Codex",
|
|
48
|
+
steps: [
|
|
49
|
+
{ run: "codex mcp add realontext -- realontext mcp" },
|
|
50
|
+
// Codex drops what a PreToolUse hook adds; SessionStart's reaches the model.
|
|
51
|
+
{ list: "~/.codex/hooks.json", at: ["hooks", "SessionStart"], value: nested("codex") },
|
|
52
|
+
],
|
|
53
|
+
hook: { event: "SessionStart" },
|
|
54
|
+
},
|
|
55
|
+
gemini: {
|
|
56
|
+
name: "Gemini CLI",
|
|
57
|
+
steps: [
|
|
58
|
+
{ run: "gemini mcp add realontext realontext mcp" },
|
|
59
|
+
// Gemini CLI drops what a BeforeTool hook adds; AfterTool's goes after the tool's result.
|
|
60
|
+
{
|
|
61
|
+
list: ".gemini/settings.json",
|
|
62
|
+
at: ["hooks", "AfterTool"],
|
|
63
|
+
value: nested("gemini", "run_shell_command|grep_search|search_file_content"),
|
|
64
|
+
},
|
|
65
|
+
],
|
|
66
|
+
hook: { event: "AfterTool" },
|
|
67
|
+
note: "Gemini CLI starts MCP servers and hooks only in trusted folders: trust this one when it asks.",
|
|
68
|
+
},
|
|
69
|
+
qwen: {
|
|
70
|
+
name: "Qwen Code",
|
|
71
|
+
steps: [
|
|
72
|
+
{ run: "qwen mcp add -s project realontext realontext mcp" },
|
|
73
|
+
// Qwen Code drops what a PreToolUse hook adds; PostToolUse's goes after the tool's result.
|
|
74
|
+
{ list: ".qwen/settings.json", at: ["hooks", "PostToolUse"], value: nested("qwen", "run_shell_command|grep_search") },
|
|
75
|
+
],
|
|
76
|
+
hook: { event: "PostToolUse" },
|
|
77
|
+
},
|
|
78
|
+
kimi: {
|
|
79
|
+
name: "Kimi Code",
|
|
80
|
+
steps: [
|
|
81
|
+
{ json: "~/.kimi-code/mcp.json", at: ["mcpServers", "realontext"], value: SERVER },
|
|
82
|
+
{
|
|
83
|
+
block: "~/.kimi-code/config.toml",
|
|
84
|
+
text: `[[hooks]]\nevent = "PostToolUse"\nmatcher = "Shell|Bash|Grep"\ncommand = "${hook("kimi")}"\n`,
|
|
85
|
+
},
|
|
86
|
+
],
|
|
87
|
+
hook: { event: "PostToolUse" },
|
|
88
|
+
},
|
|
89
|
+
copilot: {
|
|
90
|
+
name: "GitHub Copilot CLI",
|
|
91
|
+
steps: [
|
|
92
|
+
{ clear: "copilot mcp remove realontext", run: "copilot mcp add realontext -- realontext mcp" },
|
|
93
|
+
{ list: "~/.copilot/hooks/realontext.json", at: ["hooks", "sessionStart"], value: flat("copilot") },
|
|
94
|
+
],
|
|
95
|
+
hook: { event: "sessionStart", flat: true },
|
|
96
|
+
},
|
|
97
|
+
vscode: {
|
|
98
|
+
name: "VS Code (GitHub Copilot)",
|
|
99
|
+
steps: [
|
|
100
|
+
{ json: ".vscode/mcp.json", at: ["servers", "realontext"], value: { type: "stdio", ...SERVER } },
|
|
101
|
+
// VS Code ignores matchers: the reminder comes before the session's first tool call.
|
|
102
|
+
{ list: ".github/hooks/realontext.json", at: ["hooks", "PreToolUse"], value: flat("vscode") },
|
|
103
|
+
{ block: ".github/copilot-instructions.md", text: RULES },
|
|
104
|
+
],
|
|
105
|
+
hook: { event: "PreToolUse" },
|
|
106
|
+
},
|
|
107
|
+
jetbrains: {
|
|
108
|
+
name: "JetBrains (GitHub Copilot)",
|
|
109
|
+
steps: [
|
|
110
|
+
{ json: "~/.config/github-copilot/intellij/mcp.json", at: ["servers", "realontext"], value: SERVER },
|
|
111
|
+
// The hooks file VS Code reads, the same wire format.
|
|
112
|
+
{ list: ".github/hooks/realontext.json", at: ["hooks", "PreToolUse"], value: flat("vscode") },
|
|
113
|
+
{ block: ".github/copilot-instructions.md", text: RULES },
|
|
114
|
+
],
|
|
115
|
+
},
|
|
116
|
+
cursor: {
|
|
117
|
+
name: "Cursor",
|
|
118
|
+
steps: [
|
|
119
|
+
{ json: ".cursor/mcp.json", at: ["mcpServers", "realontext"], value: SERVER },
|
|
120
|
+
// Cursor does not show the model what its hooks add: the rules carry it.
|
|
121
|
+
{ file: ".cursor/rules/realontext.mdc", text: `---\ndescription: Code search with realontext\nalwaysApply: true\n---\n\n${RULES}` },
|
|
122
|
+
],
|
|
123
|
+
note: "Approve the server once: in the editor when it asks, or `cursor-agent mcp enable realontext`.",
|
|
124
|
+
},
|
|
125
|
+
opencode: {
|
|
126
|
+
name: "opencode",
|
|
127
|
+
steps: [{ json: "opencode.json", at: ["mcp", "realontext"], value: { type: "local", command: ["realontext", "mcp"] } }],
|
|
128
|
+
},
|
|
129
|
+
kilo: {
|
|
130
|
+
name: "Kilo Code",
|
|
131
|
+
steps: [{ json: "kilo.json", at: ["mcp", "realontext"], value: { type: "local", command: ["realontext", "mcp"] } }],
|
|
132
|
+
},
|
|
133
|
+
kiro: {
|
|
134
|
+
name: "Kiro",
|
|
135
|
+
steps: [
|
|
136
|
+
{ json: ".kiro/settings/mcp.json", at: ["mcpServers", "realontext"], value: SERVER },
|
|
137
|
+
{ file: ".kiro/steering/realontext.md", text: `---\ninclusion: always\n---\n\n${RULES}` },
|
|
138
|
+
],
|
|
139
|
+
},
|
|
140
|
+
antigravity: {
|
|
141
|
+
name: "Antigravity",
|
|
142
|
+
steps: [{ json: "~/.gemini/antigravity/mcp_config.json", at: ["mcpServers", "realontext"], value: SERVER }],
|
|
143
|
+
},
|
|
144
|
+
agy: {
|
|
145
|
+
name: "Antigravity CLI",
|
|
146
|
+
steps: [{ run: "agy mcp add realontext realontext mcp" }],
|
|
147
|
+
},
|
|
148
|
+
zed: {
|
|
149
|
+
name: "Zed",
|
|
150
|
+
steps: [{ json: ".zed/settings.json", at: ["context_servers", "realontext"], value: SERVER }],
|
|
151
|
+
},
|
|
152
|
+
openclaw: {
|
|
153
|
+
name: "OpenClaw",
|
|
154
|
+
steps: [{ json: "~/.openclaw/openclaw.json", at: ["mcp", "servers", "realontext"], value: SERVER }],
|
|
155
|
+
},
|
|
156
|
+
pi: {
|
|
157
|
+
name: "Pi",
|
|
158
|
+
// Pi has no MCP: the package's own extension (`pi/realontext.js`) is the bridge.
|
|
159
|
+
steps: [{ run: `pi install "${path.dirname(__dirname)}"` }],
|
|
160
|
+
},
|
|
161
|
+
omp: {
|
|
162
|
+
name: "Oh My Pi",
|
|
163
|
+
steps: [{ json: "~/.omp/agent/mcp_config.json", at: ["mcpServers", "realontext"], value: SERVER }],
|
|
164
|
+
},
|
|
165
|
+
dsh: {
|
|
166
|
+
name: "DeepSeek Harness",
|
|
167
|
+
steps: [
|
|
168
|
+
{
|
|
169
|
+
block: path.join(DSH, "cordis.patch.yml"),
|
|
170
|
+
text: [
|
|
171
|
+
"- insert:",
|
|
172
|
+
" - id: realontext",
|
|
173
|
+
" name: '@deepseek-ai/dsh-mcp-client'",
|
|
174
|
+
" config:",
|
|
175
|
+
" serverName: realontext",
|
|
176
|
+
" transport: stdio",
|
|
177
|
+
" command: realontext",
|
|
178
|
+
" args: [mcp]",
|
|
179
|
+
" cwd: !!js process.cwd()",
|
|
180
|
+
" - id: realontext-hooks",
|
|
181
|
+
" name: '@deepseek-ai/dsh-hooks-claude-code'",
|
|
182
|
+
" config:",
|
|
183
|
+
` configPath: '${path.join(DSH, "realontext-hooks.json")}'`,
|
|
184
|
+
"",
|
|
185
|
+
].join("\n"),
|
|
186
|
+
},
|
|
187
|
+
// dsh's Claude Code bridge adds no context from PreToolUse; SessionStart's reaches the model.
|
|
188
|
+
{ list: path.join(DSH, "realontext-hooks.json"), at: ["hooks", "SessionStart"], value: nested("dsh") },
|
|
189
|
+
],
|
|
190
|
+
hook: { event: "SessionStart" },
|
|
191
|
+
},
|
|
192
|
+
};
|
|
193
|
+
|
|
194
|
+
module.exports = agents;
|
package/lib/binary.js
CHANGED
|
@@ -76,19 +76,4 @@ function binary() {
|
|
|
76
76
|
// The version `binary()` runs.
|
|
77
77
|
binary.version = () => installed()?.version ?? version;
|
|
78
78
|
|
|
79
|
-
|
|
80
|
-
// first on PATH (D97). Windows spells the key as it likes, and one key it stays.
|
|
81
|
-
// Windows also looks for a bare `rg` in the current directory, the repository
|
|
82
|
-
// being searched, before PATH; NoDefaultCurrentDirectoryInExePath stops that.
|
|
83
|
-
// Nothing else reads it.
|
|
84
|
-
function env(file) {
|
|
85
|
-
const key = Object.keys(process.env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
|
|
86
|
-
const rest = process.env[key];
|
|
87
|
-
return {
|
|
88
|
-
...process.env,
|
|
89
|
-
[key]: rest ? path.dirname(file) + path.delimiter + rest : path.dirname(file),
|
|
90
|
-
NoDefaultCurrentDirectoryInExePath: "1",
|
|
91
|
-
};
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
module.exports = Object.assign(binary, { packageName, home, exe, newer, env });
|
|
79
|
+
module.exports = Object.assign(binary, { packageName, home, exe, newer });
|
package/lib/hook.js
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// `realontext hook <agent>` (D106, D107): the first time an agent's session
|
|
2
|
+
// fires the hook `setup` wrote, the model is reminded that codebase-retrieval
|
|
3
|
+
// searches source code. Once a session, and only context: the agent goes on
|
|
4
|
+
// as it would, and any failure here is silent. Which event it answers, and in
|
|
5
|
+
// what shape, is the agent's `hook` in `agents.js`.
|
|
6
|
+
"use strict";
|
|
7
|
+
|
|
8
|
+
const fs = require("fs");
|
|
9
|
+
const os = require("os");
|
|
10
|
+
const path = require("path");
|
|
11
|
+
|
|
12
|
+
// True the first time it is asked for a session, false after: a marker file
|
|
13
|
+
// per session, made atomically, since every hook call is its own process.
|
|
14
|
+
function firstTime(session) {
|
|
15
|
+
const id = String(session || process.ppid).replace(/[^\w-]/g, "");
|
|
16
|
+
try {
|
|
17
|
+
fs.closeSync(fs.openSync(path.join(os.tmpdir(), `realontext-hint-${id}`), "wx"));
|
|
18
|
+
return true;
|
|
19
|
+
} catch {
|
|
20
|
+
return false;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
module.exports = function hook(key) {
|
|
25
|
+
let raw = "";
|
|
26
|
+
process.stdin.on("data", (d) => (raw += d));
|
|
27
|
+
process.stdin.on("end", () => {
|
|
28
|
+
try {
|
|
29
|
+
const { event, flat } = require("./agents.js")[key].hook;
|
|
30
|
+
const input = JSON.parse(raw);
|
|
31
|
+
if (!firstTime(input.session_id ?? input.sessionId ?? input.conversation_id)) return;
|
|
32
|
+
const hint = fs.readFileSync(path.join(__dirname, "..", "hooks", "hint.md"), "utf8").trimEnd();
|
|
33
|
+
const out = flat ? { additionalContext: hint } : { hookSpecificOutput: { hookEventName: event, additionalContext: hint } };
|
|
34
|
+
process.stdout.write(JSON.stringify(out));
|
|
35
|
+
} catch {
|
|
36
|
+
// A reminder that cannot be given is not worth stopping the agent for.
|
|
37
|
+
}
|
|
38
|
+
});
|
|
39
|
+
};
|
package/lib/mcp.js
CHANGED
package/lib/rules.md
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
## Code search
|
|
2
|
+
|
|
3
|
+
This repository is searched with realontext, which replaces grep. Its MCP tool `codebase-retrieval` searches the code: every time you need to know where something is in the source (where or how something is done, where a name you know is defined, what calls it, where it is used, which line of a file it is on), call `codebase-retrieval` yourself, at every step of the task (if your tools are deferred, load it first). For text in docs, configs and logs, and for a command's output, run `realontext query --pattern RE [--path PATH]...` in the shell, or pipe into it: `git log | realontext query --pattern fix`. Do not run grep, rg, git grep or any other text search, as a tool or in the shell, alone or inside a longer command. Listing files by name stays with your own tools. Every call needs a `pattern`: the grep you would have run, in ripgrep's syntax: a name exactly (`truncate_name\(` for every call of it), or for a description the keywords the code must contain, broad and case-insensitive (`(?i)retry|backoff`); only code with a matching line is searched. Add a `query`, an English description of the behavior with words likely to appear in the code, when you are describing behavior: the Relay then orders the results. Leave it out for a name you know: the pattern's words answer at once. If nothing comes back, loosen the pattern; if 20 results are not enough, narrow it.
|
package/lib/setup.js
CHANGED
|
@@ -1,90 +1,91 @@
|
|
|
1
|
-
// `realontext setup [agent...]`: connects agents to `realontext mcp
|
|
2
|
-
// the
|
|
3
|
-
// With no agent named, the menu in `tui.mjs`
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
// as an older `npx` one, is replaced.
|
|
1
|
+
// `realontext setup [agent...]`: connects agents to `realontext mcp`, run from
|
|
2
|
+
// the repository root (D74). What each agent gets is in `agents.js` (D107);
|
|
3
|
+
// this file carries the steps out. With no agent named, the menu in `tui.mjs`
|
|
4
|
+
// asks which. Running it again replaces what an earlier run wrote, such as an
|
|
5
|
+
// older `npx` entry, and leaves everything else in the files as it was.
|
|
7
6
|
"use strict";
|
|
8
7
|
|
|
9
8
|
const fs = require("fs");
|
|
9
|
+
const os = require("os");
|
|
10
10
|
const path = require("path");
|
|
11
11
|
const { spawnSync } = require("child_process");
|
|
12
|
+
const agents = require("./agents.js");
|
|
12
13
|
|
|
13
|
-
const
|
|
14
|
-
claude: {
|
|
15
|
-
name: "Claude Code",
|
|
16
|
-
// `claude mcp add` refuses a name it already has in this scope.
|
|
17
|
-
clear: "claude mcp remove realontext -s local",
|
|
18
|
-
run: "claude mcp add realontext -- realontext mcp",
|
|
19
|
-
},
|
|
20
|
-
codex: {
|
|
21
|
-
name: "Codex",
|
|
22
|
-
run: "codex mcp add realontext -- realontext mcp",
|
|
23
|
-
},
|
|
24
|
-
gemini: {
|
|
25
|
-
name: "Gemini CLI",
|
|
26
|
-
run: "gemini mcp add realontext realontext mcp",
|
|
27
|
-
note: "Gemini CLI starts MCP servers only in trusted folders: trust this one when it asks.",
|
|
28
|
-
},
|
|
29
|
-
cursor: {
|
|
30
|
-
name: "Cursor",
|
|
31
|
-
file: ".cursor/mcp.json",
|
|
32
|
-
key: "mcpServers",
|
|
33
|
-
entry: { command: "realontext", args: ["mcp"] },
|
|
34
|
-
note: "Approve the server once: in the editor when it asks, or `cursor-agent mcp enable realontext`.",
|
|
35
|
-
},
|
|
36
|
-
vscode: {
|
|
37
|
-
name: "VS Code",
|
|
38
|
-
file: ".vscode/mcp.json",
|
|
39
|
-
key: "servers",
|
|
40
|
-
entry: { type: "stdio", command: "realontext", args: ["mcp"] },
|
|
41
|
-
},
|
|
42
|
-
opencode: {
|
|
43
|
-
name: "opencode",
|
|
44
|
-
file: "opencode.json",
|
|
45
|
-
key: "mcp",
|
|
46
|
-
entry: { type: "local", command: ["realontext", "mcp"] },
|
|
47
|
-
},
|
|
48
|
-
};
|
|
14
|
+
const MINE = "realontext hook"; // in every hook entry setup writes
|
|
49
15
|
|
|
50
|
-
// Through a shell, so that npm's `.cmd` wrappers run on Windows too.
|
|
51
|
-
// word is a plain one: nothing to quote.
|
|
16
|
+
// Through a shell, so that npm's `.cmd` wrappers run on Windows too.
|
|
52
17
|
function sh(command, quiet) {
|
|
53
18
|
const run = spawnSync(command, { shell: true, stdio: quiet ? "ignore" : "inherit" });
|
|
54
19
|
if (run.error) throw run.error;
|
|
55
20
|
return run.status ?? 1;
|
|
56
21
|
}
|
|
57
22
|
|
|
58
|
-
function
|
|
23
|
+
function where(file) {
|
|
24
|
+
return file.startsWith("~/") ? path.join(os.homedir(), file.slice(2)) : file;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function save(file, text) {
|
|
28
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
29
|
+
fs.writeFileSync(file, text);
|
|
30
|
+
console.error(`realontext: wrote ${file}`);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// The JSON at `file` with `change` made to the value at the key path `at`.
|
|
34
|
+
function edit(file, at, change) {
|
|
59
35
|
let config = {};
|
|
60
|
-
if (fs.existsSync(
|
|
36
|
+
if (fs.existsSync(file)) {
|
|
61
37
|
try {
|
|
62
|
-
config = JSON.parse(fs.readFileSync(
|
|
38
|
+
config = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
63
39
|
} catch (e) {
|
|
64
|
-
throw new Error(
|
|
65
|
-
`${agent.file} is not plain JSON (${e.message}); add this under "${agent.key}" by hand:\n` +
|
|
66
|
-
JSON.stringify({ realontext: agent.entry }, null, 2)
|
|
67
|
-
);
|
|
40
|
+
throw new Error(`${file} is not plain JSON (${e.message}); add this at ${at.join(" > ")} by hand:\n` + JSON.stringify(change(undefined), null, 2));
|
|
68
41
|
}
|
|
69
42
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
return 0;
|
|
43
|
+
const parent = at.slice(0, -1).reduce((o, k) => (o[k] = o[k] ?? {}), config);
|
|
44
|
+
const key = at[at.length - 1];
|
|
45
|
+
parent[key] = change(parent[key]);
|
|
46
|
+
save(file, JSON.stringify(config, null, 2) + "\n");
|
|
75
47
|
}
|
|
76
48
|
|
|
49
|
+
// `text` between two marker lines at the end of `file`, in place of the ones there.
|
|
50
|
+
function block(file, text) {
|
|
51
|
+
const [open, close] = file.endsWith(".md")
|
|
52
|
+
? ["<!-- >>> realontext -->", "<!-- <<< realontext -->"]
|
|
53
|
+
: ["# >>> realontext", "# <<< realontext"];
|
|
54
|
+
const old = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
|
|
55
|
+
const start = old.indexOf(open);
|
|
56
|
+
const end = old.indexOf(close, start);
|
|
57
|
+
const rest = start < 0 || end < 0 ? old : old.slice(0, start) + old.slice(end + close.length).replace(/^\r?\n/, "");
|
|
58
|
+
const head = rest.trimEnd();
|
|
59
|
+
save(file, `${head}${head ? "\n\n" : ""}${open}\n${text.trimEnd()}\n${close}\n`);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function step(s) {
|
|
63
|
+
if (s.run) {
|
|
64
|
+
if (s.clear) sh(s.clear, true);
|
|
65
|
+
const status = sh(s.run, false);
|
|
66
|
+
if (status !== 0) throw new Error(`\`${s.run}\` exited with ${status}`);
|
|
67
|
+
} else if (s.json) {
|
|
68
|
+
edit(where(s.json), s.at, () => s.value);
|
|
69
|
+
} else if (s.list) {
|
|
70
|
+
const ours = (e) => JSON.stringify(e).includes(MINE);
|
|
71
|
+
edit(where(s.list), s.at, (list) => [...(Array.isArray(list) ? list.filter((e) => !ours(e)) : []), s.value]);
|
|
72
|
+
} else if (s.block) {
|
|
73
|
+
block(where(s.block), s.text);
|
|
74
|
+
} else {
|
|
75
|
+
save(where(s.file), s.text);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// The steps run in order; the first that fails stops this agent.
|
|
77
80
|
function connect(agent) {
|
|
78
|
-
let status;
|
|
79
81
|
try {
|
|
80
|
-
|
|
81
|
-
status = agent.file ? write(agent) : sh(agent.run, false);
|
|
82
|
+
agent.steps.forEach(step);
|
|
82
83
|
} catch (e) {
|
|
83
|
-
console.error(`realontext: ${e.message}`);
|
|
84
|
+
console.error(`realontext: ${agent.name}: ${e.message}`);
|
|
84
85
|
return 1;
|
|
85
86
|
}
|
|
86
|
-
if (
|
|
87
|
-
return
|
|
87
|
+
if (agent.note) console.error(agent.note);
|
|
88
|
+
return 0;
|
|
88
89
|
}
|
|
89
90
|
|
|
90
91
|
// Every agent named gets its turn; one failing does not stop the rest.
|
package/lib/update.js
CHANGED
|
@@ -77,12 +77,6 @@ async function install(v) {
|
|
|
77
77
|
const tmp = `${dir}.${process.pid}`;
|
|
78
78
|
fs.mkdirSync(tmp, { recursive: true });
|
|
79
79
|
fs.writeFileSync(path.join(tmp, binary.exe), file, { mode: 0o755 });
|
|
80
|
-
// ripgrep, which the binary runs from PATH with its own directory first
|
|
81
|
-
// (D97); a version from before it has none.
|
|
82
|
-
const rg = process.platform === "win32" ? "rg.exe" : "rg";
|
|
83
|
-
try {
|
|
84
|
-
fs.writeFileSync(path.join(tmp, rg), untar(tar, `package/bin/${rg}`), { mode: 0o755 });
|
|
85
|
-
} catch {}
|
|
86
80
|
try {
|
|
87
81
|
fs.renameSync(tmp, dir);
|
|
88
82
|
} catch (e) {
|
package/package.json
CHANGED
|
@@ -1,20 +1,30 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "realontext",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "Code search for coding agents, over the directory you are in. CLI and MCP server.",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://github.com/frevlm/realontext.git",
|
|
9
|
-
"directory": "npm/realontext"
|
|
9
|
+
"directory": "client/npm/realontext"
|
|
10
10
|
},
|
|
11
|
+
"keywords": [
|
|
12
|
+
"pi-package"
|
|
13
|
+
],
|
|
11
14
|
"bin": {
|
|
12
15
|
"realontext": "bin/realontext.js"
|
|
13
16
|
},
|
|
17
|
+
"pi": {
|
|
18
|
+
"extensions": [
|
|
19
|
+
"./pi/realontext.js"
|
|
20
|
+
]
|
|
21
|
+
},
|
|
14
22
|
"files": [
|
|
15
23
|
".claude-plugin/",
|
|
16
24
|
"bin/realontext.js",
|
|
17
|
-
"
|
|
25
|
+
"hooks/",
|
|
26
|
+
"lib/",
|
|
27
|
+
"pi/"
|
|
18
28
|
],
|
|
19
29
|
"engines": {
|
|
20
30
|
"node": ">=18"
|
|
@@ -24,8 +34,8 @@
|
|
|
24
34
|
"react": "^18.3.1"
|
|
25
35
|
},
|
|
26
36
|
"optionalDependencies": {
|
|
27
|
-
"@realontext/darwin-arm64": "0.
|
|
28
|
-
"@realontext/linux-x64": "0.
|
|
29
|
-
"@realontext/win32-x64": "0.
|
|
37
|
+
"@realontext/darwin-arm64": "0.12.0",
|
|
38
|
+
"@realontext/linux-x64": "0.12.0",
|
|
39
|
+
"@realontext/win32-x64": "0.12.0"
|
|
30
40
|
}
|
|
31
41
|
}
|
package/pi/realontext.js
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
// The Pi extension (D107). Pi has no MCP client, so this is one, for
|
|
2
|
+
// `realontext mcp` alone: it starts the server with this package's own
|
|
3
|
+
// command, registers the tools the server lists, with their names,
|
|
4
|
+
// descriptions and schemas as they are, and appends the server's
|
|
5
|
+
// instructions to the system prompt. A tool call is a `tools/call`; what the
|
|
6
|
+
// server answers goes back to the model.
|
|
7
|
+
"use strict";
|
|
8
|
+
|
|
9
|
+
const path = require("path");
|
|
10
|
+
const readline = require("readline");
|
|
11
|
+
const { spawn } = require("child_process");
|
|
12
|
+
const { Type } = require("typebox");
|
|
13
|
+
|
|
14
|
+
const BIN = path.join(__dirname, "..", "bin", "realontext.js");
|
|
15
|
+
|
|
16
|
+
// A JSON-RPC session over the server's stdio: `ask` sends a request and
|
|
17
|
+
// resolves to its result, or rejects with its error.
|
|
18
|
+
function connect() {
|
|
19
|
+
const child = spawn(process.execPath, [BIN, "mcp"], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
|
|
20
|
+
const waiting = new Map();
|
|
21
|
+
let next = 1;
|
|
22
|
+
const fail = (e) => {
|
|
23
|
+
for (const { reject } of waiting.values()) reject(e);
|
|
24
|
+
waiting.clear();
|
|
25
|
+
};
|
|
26
|
+
child.on("error", fail);
|
|
27
|
+
child.on("exit", () => fail(new Error("realontext mcp exited")));
|
|
28
|
+
child.stdin.on("error", () => {});
|
|
29
|
+
readline.createInterface({ input: child.stdout, crlfDelay: Infinity }).on("line", (line) => {
|
|
30
|
+
let m;
|
|
31
|
+
try {
|
|
32
|
+
m = JSON.parse(line);
|
|
33
|
+
} catch {
|
|
34
|
+
return;
|
|
35
|
+
}
|
|
36
|
+
const w = waiting.get(m.id);
|
|
37
|
+
if (!w) return;
|
|
38
|
+
waiting.delete(m.id);
|
|
39
|
+
m.error ? w.reject(new Error(m.error.message)) : w.resolve(m.result);
|
|
40
|
+
});
|
|
41
|
+
const send = (m) => child.stdin.write(JSON.stringify({ jsonrpc: "2.0", ...m }) + "\n");
|
|
42
|
+
return {
|
|
43
|
+
ask: (method, params) =>
|
|
44
|
+
new Promise((resolve, reject) => {
|
|
45
|
+
const id = next++;
|
|
46
|
+
waiting.set(id, { resolve, reject });
|
|
47
|
+
send({ id, method, params });
|
|
48
|
+
}),
|
|
49
|
+
tell: (method, params) => send({ method, params }),
|
|
50
|
+
close: () => child.stdin.end(),
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
module.exports = async function (pi) {
|
|
55
|
+
const server = connect();
|
|
56
|
+
const init = await server.ask("initialize", {
|
|
57
|
+
protocolVersion: "2025-06-18",
|
|
58
|
+
capabilities: {},
|
|
59
|
+
clientInfo: { name: "pi", version: "0" },
|
|
60
|
+
});
|
|
61
|
+
server.tell("notifications/initialized");
|
|
62
|
+
const { tools } = await server.ask("tools/list", {});
|
|
63
|
+
|
|
64
|
+
for (const tool of tools) {
|
|
65
|
+
pi.registerTool({
|
|
66
|
+
name: tool.name,
|
|
67
|
+
label: tool.title || tool.name,
|
|
68
|
+
description: tool.description,
|
|
69
|
+
parameters: Type.Unsafe(tool.inputSchema),
|
|
70
|
+
async execute(_id, params) {
|
|
71
|
+
const result = await server.ask("tools/call", { name: tool.name, arguments: params });
|
|
72
|
+
const content = result.content.filter((c) => c.type === "text");
|
|
73
|
+
if (result.isError) throw new Error(content.map((c) => c.text).join("\n"));
|
|
74
|
+
return { content, details: {} };
|
|
75
|
+
},
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
if (init.instructions) {
|
|
80
|
+
pi.on("before_agent_start", (event) => ({ systemPrompt: `${event.systemPrompt}\n\n${init.instructions}` }));
|
|
81
|
+
}
|
|
82
|
+
pi.on("session_shutdown", () => server.close());
|
|
83
|
+
};
|