Skip to content
Back to search

xks-toolintercept-folder_mngmt

Folder and naming decisions for coding agents, asked of a Jev-like model by a fixed standard (xks-folder/1): MCP server and Claude Code hook over any System One server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lasimeri--xks-toolintercept-folder-mngmt/badge.svg)](/listings/lasimeri--xks-toolintercept-folder-mngmt)

HTML

<a href="/listings/lasimeri--xks-toolintercept-folder-mngmt"><img src="/api/listings/lasimeri--xks-toolintercept-folder-mngmt/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/Lasimeri/xks-toolintercept-folder_mngmt
cd xks-toolintercept-folder_mngmt
make                # target/release/xtf
make install        # ~/.local/bin/xtf (PREFIX=... for another place)
make check          # unit tests and clippy, no model needed

The binary is small and links no model: the model runs in the decision server.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 269 lines
  1. # xks-toolintercept-folder_mngmt
  2. Folder and naming decisions for coding agents, asked of a Jev-like model the
  3. same way in every project.
  4. A coding agent creates files and folders all day, and every project ends up
  5. laid out by whatever the agent guessed at the time. This project fixes the
  6. questions instead: a project describes its layout once, in a small JSON
  7. manifest, and every "where does this new file go, and is it named right?"
  8. becomes the same fixed, typed question, answered by a System One model
  9. (TypeSafe's Jev, or a local Jev-like model), acted on only when the model is
  10. confident, and written down.
  11. **Status: 0.4.0.** The standard ([xks-folder/1](SPEC.md)), its Rust
  12. library and `xtf` command line, its calibration on six real repositories,
  13. and the **Claude Code plugin** that puts it in front of every session
  14. automatically: a hook on every new file and folder, an MCP server (new
  15. projects, placements, whole planned trees, names, layout changes), and one
  16. shared model instance as a user service ([Claude Code](#claude-code)). A
  17. folder outside the layout is read by the model against every role it can
  18. play when a tool call creates it, and since 0.4.0 the hook records a
  19. confident reading in the manifest: the layout grows one folder at a time,
  20. decided by the model, not laid out up front.
  21. ## How a decision is made
  22. 1. **Provided JSON, the manifest** (`xks-project.json` at the project root):
  23. name, purpose, languages, and which of 13 fixed roles (source, tests,
  24. docs, tools, out, ...) each top-level folder plays.
  25. 2. **Projected JSON, the operation**: a file or folder about to be created
  26. (or moved, renamed), with a short summary of what it holds.
  27. 3. **Rules first**, no model: deletions and generated or vendored paths are
  28. left alone; conventional top-level files (README, LICENSE, Makefile,
  29. Cargo.toml, dotfiles) are fine where they are; test and benchmark files
  30. are recognised by their names; a file's extension rules out roles it
  31. cannot play; source file names are checked against the project's naming
  32. style (snake_case, kebab-case, ...).
  33. 4. **Fixed questions**, when the rules leave it open: "Which part of the
  34. project does it belong in?", its options the project's roles with fixed
  35. descriptions; "Does the name tell a reader what the file holds?". The same
  36. wording in every project. The model never writes a path or a name; it
  37. picks among options, and its probabilities say how sure it is.
  38. 5. **Policy**: a different place is suggested only when the Choice
  39. confidence is at least 0.5 (TypeSafe's floor for "genuinely unsure", and
  40. the calibrated value below); otherwise the operation is left as it is and
  41. marked uncertain.
  42. 6. **Record**: every decision goes to `.xks/decisions.jsonl`, the model's
  43. answers verbatim.
  44. The full standard is [SPEC.md](SPEC.md).
  45. ## Requirements
  46. - Rust 1.85 or newer (to build).
  47. - A System One decision server:
  48. - [`jevbase serve`](https://github.com/Lasimeri/XKS_Jev-like_Model_Base)
  49. (a local Jev-like model on the CPU; the default, at
  50. `http://127.0.0.1:8097`), or
  51. - Intel-Phi-Jev's `xks serve`, or
  52. - TypeSafe's hosted Jev (`https://api.typesafe.ai`, with an API key; the
  53. `curl` program must be installed for https).
  54. `xtf init` needs no server.
  55. ## Install
  56. ```sh
  57. git clone https://github.com/Lasimeri/xks-toolintercept-folder_mngmt
  58. cd xks-toolintercept-folder_mngmt
  59. make # target/release/xtf
  60. make install # ~/.local/bin/xtf (PREFIX=... for another place)
  61. make check # unit tests and clippy, no model needed
  62. ```
  63. The binary is small and links no model: the model runs in the decision
  64. server.
  65. ## Quick start
  66. ```sh
  67. jevbase serve & # the decision server (XKS_Jev-like_Model_Base)
  68. cd my-project
  69. xtf init . --purpose "A CLI that syncs photo folders to a NAS." --lang rust
  70. $EDITOR xks-project.json # check the layout it guessed
  71. xtf check src/thumbnails.rs --summary "//! Builds JPEG thumbnails for the sync preview."
  72. ```
  73. `check` prints the decision as JSON and appends it to `.xks/decisions.jsonl`.
  74. Every command is described in [docs/cli.md](docs/cli.md).
  75. ## Claude Code
  76. One command makes it automatic in every Claude Code session and project on
  77. the machine:
  78. ```sh
  79. make install-claude
  80. ```
  81. It installs a Claude Code plugin (a directory marketplace under
  82. `~/.local/share/xtf/claude-code`, enabled at user scope) and the decision
  83. server as a systemd user service (`jevbase.service`: `jevbase serve` on
  84. 127.0.0.1:8097, the model held in RAM, started at login). `jevbase` itself
  85. comes from [XKS_Jev-like_Model_Base](https://github.com/Lasimeri/XKS_Jev-like_Model_Base)
  86. (its release archive, or `make install` there). Every session then shares
  87. that one model instance.
  88. What every session gets:
  89. | piece | when | what it does |
  90. |---|---|---|
  91. | `xtf-hook session-start` | a session starts, resumes, clears or compacts | tells Claude the project's layout and naming from `xks-project.json` (or that the project has none, and how one is written); no model call, under 1 ms |
  92. | `xtf-hook pre-tool-use` | every `Write` of a new file, every `mkdir` | the model decides the new path against the manifest; when it is confident (>= 0.5) the file belongs elsewhere, or a name breaks the naming style, the first attempt is denied with the suggested path, and the same attempt again goes through (`XTF_HOOK_MODE=enforce`, the default; `advise` adds the suggestion as context only; `off`) |
  93. | MCP tool `new_project` | Claude starts a project | the model decides the project's kind, the standard lays out its folders for that kind and language, the manifest is written and the folders created |
  94. | MCP tools `place_file`, `plan_tree`, `pick_name`, `project_info` | Claude asks | one placement, a whole planned folder tree, a name among candidates, the project's manifest and decision count |
  95. Outside any project, a new file or folder gets a note (once per session and
  96. folder) that `new_project` or `xtf init` writes a manifest; nothing is
  97. blocked. Every decision is appended to the project's `.xks/decisions.jsonl`.
  98. A decision server that is down, busy past 15 s or refusing never blocks
  99. Claude: the hook lets the operation through and records why in
  100. `~/.cache/xtf/hook/errors.log`. Details: [docs/hook.md](docs/hook.md),
  101. [docs/mcp.md](docs/mcp.md).
  102. Checked with Claude Code 2.1.316 itself (`claude -p` on this machine,
  103. 2026-11-21, Qwen3.8 2B Q8_0 behind the server):
  104. | test | result |
  105. |---|---|
  106. | a session in a project | plugin loaded, MCP server connected, the five tools offered, the layout given at session start |
  107. | a Rust source file written into `docs/` | decided by the model: source, confidence 0.47, under 0.5, so left as is (4.2 s) |
  108. | `src/ParseFlags.rs` in a snake_case project | denied with `src/parse_flags.rs` suggested (3.3 s); the session wrote the same path again, as its prompt named it, and the hook let it through |
  109. | "lay out a new project" through `new_project` | kind cli-tool decided by the model at confidence 0.85, manifest written, `src/ tests/ docs/ out/` created |
  110. | three sessions writing new files at the same time | all three decided (4.2 s, 5.3 s, 5.7 s, the queue included), none timed out, the shared decision log intact |
  111. ## Configuration
  112. The decision server is configured the way TypeSafe's SDKs are:
  113. | variable | default |
  114. |---|---|
  115. | `TYPESAFE_BASE_URL` | `http://127.0.0.1:8097` (`jevbase serve`) |
  116. | `TYPESAFE_API_KEY` | none (needed for the hosted Jev) |
  117. | `TYPESAFE_DEFAULT_MODEL` | `jev-latest` |
  118. Any server that speaks TypeSafe's documented `POST /v1/systemone` answers
  119. the standard's questions; the thresholds were calibrated with `jevbase
  120. serve` and its default model (Qwen3.8 2B Q8_0), so re-run the calibration
  121. when you use another.
  122. ## The manifest
  123. ```json
  124. {
  125. "standard": "xks-folder/1",
  126. "name": "photo-sync",
  127. "purpose": "A CLI that syncs photo folders to a NAS.",
  128. "languages": ["rust"],
  129. "layout": {
  130. "source": ["src"],
  131. "tests": ["tests"],
  132. "docs": ["docs"],
  133. "tools": ["scripts"],
  134. "out": ["out"]
  135. },
  136. "naming": { "files": "snake_case", "dirs": "any" },
  137. "ignore": [".git", "target"]
  138. }
  139. ```
  140. Roles: source, include, tests, benches, examples, docs, tools,
  141. integrations, data, assets, third_party, out, and config (the root itself).
  142. A role may map to several folders (`"source": ["src", "cli", "tui"]`) or to a
  143. nested one (`"src/tui"`). `out`, `third_party` and `ignore` paths are never
  144. decided on. Naming styles: `snake_case`, `kebab-case`, `PascalCase`,
  145. `camelCase`, `lowercase`, `any`; the file style applies to the project's own
  146. source files only. Details in [SPEC.md](SPEC.md#the-documents).
  147. ## Calibration
  148. Measured with `jevbase serve` (Qwen3.8 2B Q8_0, a Ryzen 7 5800X, 8 threads)
  149. on 141 real files of six public repositories, each labelled by the role of
  150. the folder it lives in; 23 conventional top-level files are settled by the
  151. rules, the other 118 are counted (those a name or extension rule leaves one
  152. role for are settled without asking, and counted):
  153. | standard version | right overall | at confidence >= 0.5: answered / right / would move a right file | speed |
  154. |---|---|---|---|
  155. | v1, every role offered | 51.7% | 25.4% / 80.0% / 5.1% | 0.22 decisions/s |
  156. | v2, options narrowed by extension | 59.3% | 32.2% / 89.5% / 3.4% | 0.28 decisions/s |
  157. | v3, v2 + test and benchmark file names (0.1.0) | 61.0% | 33.1% / 92.3% / 2.5% | 0.33 decisions/s |
  158. In plain words: when the model is at least 0.5 confident (a third of new
  159. files), 36 of its 39 answers are right, and it would flag 3 of the 118
  160. correctly placed files (one in forty). Below that it is left alone. The set, the
  161. labels, the per-file results and how to reproduce them are in
  162. [`calibration/`](calibration) and [SPEC.md](SPEC.md#calibration).
  163. ## Using the library
  164. ```rust
  165. use std::path::Path;
  166. use xtf_standard::{Action, Decider, Manifest, Op, Projection};
  167. let path = Path::new("my-project/src/thumbnails.rs");
  168. let content = "//! Builds JPEG thumbnails for the sync preview.";
  169. let root = Manifest::find_root(path).ok_or("no xks-project.json above the path")?;
  170. let manifest = Manifest::load(&root)?;
  171. let projection = Projection {
  172. op: Op::CreateFile,
  173. path: "src/thumbnails.rs".into(),
  174. from: None,
  175. summary: xtf_standard::projection::summary_of(content),
  176. tool: None,
  177. };
  178. let decision = Decider::new(xtf_standard::client(None)).decide(&manifest, &projection)?;
  179. xtf_standard::decide::log(&root, &projection, &decision)?;
  180. if decision.verdict.action == Action::Suggest {
  181. println!("the standard suggests {:?}", decision.verdict.suggested_path);
  182. }
  183. ```
  184. (The same code is the crate's doc example and is compiled by `cargo test`.)
  185. `catalog` builds the questions, `policy` turns answers into verdicts,
  186. `naming` checks and converts names; every module is documented in its source.
  187. ## Limitations
  188. - **Accuracy of the default model.** The 2B model is right a little more
  189. often than not overall; the confidence gate is what makes it usable.
  190. Tests, examples and data files that are only recognisable by their folder
  191. are its weakest cases.
  192. - **Latency.** A placement question takes about 3.2 s on an 8-core CPU (v3
  193. calibration: 356.6 s for 111 questions sent five to a request; each is
  194. read three times, once per rotation of its options). Questions about one
  195. project share a cached state, so the first decision on a project costs
  196. more than the next.
  197. - **One request at a time.** `jevbase serve` answers requests in turn, so
  198. sessions deciding at once queue behind each other (three at once: 4.2 to
  199. 5.7 s each). A hook that waits past 15 s lets its operation through
  200. undecided; that takes about five decisions arriving together, or one
  201. behind a long `plan_tree` request. Requests carry at most 4 questions and
  202. 1,400 bytes of questions: on a 12-path plan the longest held the server
  203. 4.8 s (it was 10.6 s with a cap of 4 questions alone), so a hook queued
  204. behind one keeps about 10 s of its 15 s.
  205. - **Inside a mapped folder, a new folder is judged by its name.** A new
  206. top-level folder is asked against every role and can be confident
  207. (`scripts/` read as tools at 0.92, and the layout change offered), but a
  208. new folder inside `src/` or `docs/` has only its name and the shell
  209. command's description to go on, and those answers stayed under 0.5.
  210. - **Local sessions only.** Claude Code's cloud sessions do not read the
  211. local `~/.claude`, and the server listens on 127.0.0.1.
  212. - **Text only.** Images and binary files are not read.
  213. - **The layout is yours to write.** `xtf init` maps common folder names; a
  214. manifest is only as good as its layout.
  215. ## Roadmap
  216. - A decision server that serves several requests at once, each project's
  217. state cached in its own sequence (XKS_Jev-like_Model_Base).
  218. - A placement question that sees where the path is going, and richer
  219. evidence for new folders, so folder decisions can reach the confidence
  220. the policy acts on (a new standard version, recalibrated).
  221. - Calibration against more repositories and other decision models.
  222. ## License
  223. MIT or Apache-2.0, at your option. See [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.