11 KiB
Extending Craft Anything
Every part people tend to change sits behind a seam: a trait or a table with built-in entries and one
place to add yours. Follow AGENTS.md (never crash, layers, external programs through
craft_anything_platform::process) and give each addition tests.
| You want to add | Where | How |
|---|---|---|
| A tool | crates/engine/src/tools/<area>.rs |
A ToolSpec (id per tool-ids.md, title, summary, beginner text, toolset, honest effects, a schemars params type, run), and one v.extend(<area>::specs()) line in tools/mod.rs. It's then a CLI command, an MCP tool and callable by the agent and the app. It runs only in Deep mode until it's listed in crates/engine/src/clean_room.rs; list it there only if it touches no target or watches from outside, as a visitor or user would. |
| A tool from a higher layer | that crate, e.g. crates/ai/src/rebuild/tools.rs |
Static ToolSpecs passed to Engine::shared(session, extra); reach the engine through ctx.session.ext.get::<EngineRef>(). Never block a tool on work that calls back into the engine: start it and return. |
| A kind of thing to make | crates/ai/src/rebuild/kinds/ |
Implement TargetKind (detection score, default stack, brief sections, checks, refine message (worded for a builder that can or can't look at pictures: BriefCx::sees_pictures), the app's words) and KindRegistry::register it. |
| A way to judge a build | crates/ai/src/rebuild/kinds/ |
Implement Check (run(&mut CheckCx) -> CheckResult; applies to skip it in some runs, or wrap it in DeepOnly); return it from your kind's checks. Decide on passed/similarity, never on text. Record unmeasured comparisons in unknowns; can_refine may return false when another builder turn cannot resolve them (forward it through wrappers). A check's own program runs go through cx.stop(), whose CheckStop carries the person's Pause and the round's time limit, so a step that hangs makes no silent wait. |
| A stack | crates/ai/src/rebuild/stacks.toml |
One [[stack]] entry: name, the builder's steps, the phrases that ask for it, its engine, the package.json or Cargo.toml dependencies that show a build uses it, the files that show a person's own folder is built with it. A component or styling library is a [[library]] entry (name, phrases, the stacks it works with, steps). |
| A way to build, test or launch a project | crates/engine/src/toolchains.toml |
One [[toolchain]] entry: name, marker files, build/test commands, no-tests messages and optional launch recipes. Earlier markers win; standalone_entrypoints detects script-only projects only after every manifest has been checked. Each launch recipe has a file and argv command: an exact path, a suffix in a fixed folder (*.csproj, target/*.jar), or one named file in each child of a fixed folder (cmd/*/main.go, */__main__.py). {file} substitutes the matching relative filename without a shell, {package} its folder as ./<folder>, {module} its folder as a Python module name. runnable_jar = true counts only jars whose manifest names a Main-Class. Only a root (non-wildcard) entrypoint makes a folder a standalone_entrypoints project. A wildcard entrypoint must match exactly one file within the bounded scan. local_programs and windows_program replace the toolchain's own program (its build or test command's) in build, test and launch, not another one such as Maven's java. Packaged programs, Electron and Godot keep priority. AI's stacks::Toolchain and toolchain_in re-export this shared catalogue. |
| A coding agent | crates/ai/src/cli_agents/adapters.rs |
Implement AgentAdapter (args, required flags, stream parsing, resume, sign-in check) and register it in AgentAdapters. A native agent also goes in cli_agents::KNOWN and BackendKind::AgentCli::suggested_models, so Detect finds it and Settings offers it. Use has_model_catalog, model_catalog, validate_model and the shared AgentModel/ModelContext picker and tools for model/thinking selection; set model_catalog_depends_on_selection when metadata depends on the selected model. ACP agents also get a row in cli_agents::acp::ACP_AGENTS; if their ACP mode takes the backend's model, a row in ACP_MODEL_FLAGS too. Flags that belong after those mode words go in acp_mode_options, a trailing subcommand such as Grok Build's stdio in acp_trailing, and options applied with session/set_config_option after the session opens in acp_session_config. Set acp_mcp_stdio_type only when that agent's session list requires "type": "stdio" on our MCP server (Grok Build does; other agents do not). Refuse an access mode in validate_access when the agent cannot hold that mode (Grok Build refuses Clean room, deep chat, and questions). Override ACP startup options, process setup or requires_acp when needed. Also add its row to cli_agents::grants (DECLARED: our tool server, approvals, a note mid-turn, and how the run reaches the agent), which is what a builder gets of ours; a test fails until the row is there and matches the arguments or session, so verify actual tool exposure, not only startup. |
| An asset provider | crates/engines/src/assets/ |
Implement AssetProvider (key_env names its environment variable); add its models and prices to assets.toml. Its key is its own: assets_key_set with provider, kept as assets:<id>. |
| An external engine | crates/engines/src/table.rs |
One ExternalEngine entry (exes, known paths, what it's for, install pins with SHA-256 checked against the publisher), plus a tool_paths! id in settings.rs if people can point at their own install. |
| A front end for builds | anywhere above L5 | Hold a rebuild::RunSet (it queues past its limit) and poll it; test it with RunSet::with_starter(StandIns::starter()), whose runs report only what the test sends. |
| A persisted file | its owner module | A version field and a migration step; see file-formats.md. |
| A screen, a control or a size in the desktop app | crates/ui-egui/src/ |
Use the components in widgets.rs and the scale in theme.rs; a new size or colour goes into the scale, never into a screen. See the design system. |
| A UI language | crates/ui-egui/src/i18n/ and i18n.rs |
Add a TSV catalog and a language registry entry; preserve placeholders and run the catalog tests and cargo xtask i18n-coverage. See localisation for scope and font setup. |
Plugins: external MCP servers
Any MCP server, local (stdio) or remote (Streamable HTTP), can add tools without changing code.
Add it in Settings → Plugins, with plugins_add (craft-anything-cli plugins-add --id notes --command notes-mcp --args '["--stdio"]'), or list it in config.toml. A plugin added through the tool
or the app always asks before each call; plugins_remove takes one away.
[[plugins.mcp]]
id = "notes" # its toolset id; its tools become notes_<tool>
name = "Notes" # shown to people (default: the id)
command = "notes-mcp"
args = ["--stdio"]
consent = true # ask before each call (the default): it runs someone else's code
# enabled = false # keep it configured but off
# env = { NOTES_DIR = "C:/notes" }
[[plugins.mcp]]
id = "docs" # a remote server: url instead of command
url = "https://mcp.example.com/mcp" # https, or http:// to this computer
headers = { Authorization = "Bearer …" }
Then craft-anything-cli plugins-refresh --allow-run starts it once and caches its tool list; from
the next start its tools are offered everywhere, in a toolset of their own (MCP agents enable it with
enable_toolset). plugins-list shows what's configured and cached.
- A local server starts on its first call and stays up for the session; one that exits is started again. A remote one is reached on its first call; its session id is sent back with each request.
- Effects come from the server's tool annotations (
readOnlyHint,destructiveHint,openWorldHint), plus launching a process (local) or the network (remote). Withconsent = trueevery call asks first. envandheadersvalues are never shown bysettings_showorplugins_list.- Another transport implements
engines::mcp_client::Transportand is passed toMcpClient::with_transport. - Results are recorded as evidence from an external service (
engine: plugin:<id>). - Tool ids are
<plugin id>_<tool name>, lower-cased with_for anything else; a clash is skipped and logged.
Plugins: WASM components
A build with --features wasm-plugins (it compiles wasmtime, so it's off by default) also loads
WASM components. A component exports craft-anything:plugin/tools from
crates/engines/wit/plugin.wit: describe returns its tools
(name, title, description, input schema) as JSON, and call(name, input) answers
{"ok": …} or {"error": "…"}. List it in config.toml:
[[plugins.wasm]]
id = "wordtools" # its toolset id; its tools become wordtools_<tool>
path = "C:/plugins/wordtools.wasm"
- It may also (or instead) export
craft-anything:plugin/checks: ways of judging a build, run after the built-in checks of each round for the kinds of project they name. A check gets the build as JSON (every file's path and size, plus the text of the extensions it asks for) and answers passed, an optional 0-100 similarity and a summary; a failed one is shown to the builder to fix. Asset providers can't be plugins: they need the network. - It may import nothing: no files, network, environment or clock, so its tools run without asking.
- Each call runs in a fresh instance with a work limit (fuel) and 256 MiB of memory; one that runs past them is stopped with an error.
- A plugin that can't be loaded, or a tool whose id is invalid or taken, is skipped and logged.
- Complete plugins in Rust, with build steps: a tool,
examples/wasm-plugin-wordcount, and a check,examples/wasm-plugin-readme-check.
Plugin API versions
The plugin API is package craft-anything:plugin@<version> in plugin.wit, versioned with semver;
a plugin exports the interfaces at the version it was built against
(craft-anything:plugin/tools@0.1.0).
- Compatible means the same major version, and while it's 0.x the same minor too (0.1.0 and 0.1.7 work together; 0.2.0 doesn't). Craft Anything loads a compatible plugin whatever its patch version, and refuses an incompatible one by name ("exports … for API 0.2.0; this Craft Anything speaks 0.1.0") instead of silently skipping it.
- A patch version only adds optional JSON fields: in what a plugin returns (Craft Anything ignores fields it doesn't know) and in what it's given (plugins must ignore unknown fields too).
- A minor version (while 0.x) or a major one is anything else: a new or changed function, a
field that becomes required, a changed meaning. The host's
API_VERSION(engines::wasm_plugin) and the WIT package move together; a test checks they agree.
Code that defines tools at run time itself (a WASM host, a proxy for another protocol) uses
registry::RuntimeTool with Engine::shared_with: owned names, a JSON schema, and a function that
serves its tools, telling them apart by ctx.tool.