Skip to content

Craft Anything: understand how any software works, and craft your own.

Rust

Maki works as a coding agent, over ACP or one message at a time (R2.2) (#393)

zeller-lorenz2b2e8f5287bc
diff --git a/README.md b/README.md
index e2876f5f..0d87bdd4 100644
--- a/README.md
+++ b/README.md
@@ -152,7 +152,9 @@ Building needs a coding agent on your computer. **Claude Code** is supported fir
Anything runs your own, unmodified `claude` program, which uses your own sign-in; Craft Anything
never sees or handles your account. Your use of it falls under your own agreement with
Anthropic. See [docs/claude-code.md](docs/claude-code.md) for how and why. A Codex adapter
-exists but hasn't been verified on a real install yet. Anthropic, OpenAI, OpenRouter and local
+exists but hasn't been verified on a real install yet. Other agents that speak ACP (Gemini CLI,
+Qwen Code, opencode, goose, Hermes, Maki) can be switched to it per backend; of those, only Maki has
+been run live. Anthropic, OpenAI, OpenRouter and local
OpenAI-compatible servers are available for questions and analysis (Settings → AI).
## Built for agents
diff --git a/crates/ai/src/cli_agents/acp.rs b/crates/ai/src/cli_agents/acp.rs
index d3792d08..22235af1 100644
--- a/crates/ai/src/cli_agents/acp.rs
+++ b/crates/ai/src/cli_agents/acp.rs
@@ -22,8 +22,28 @@ use std::sync::{Arc, PoisonError};
use std::time::Duration;
/// Agents known to speak ACP, and the arguments that start them in that mode.
-pub const ACP_AGENTS: &[(&str, &[&str])] =
- &[("gemini-cli", &["--experimental-acp"]), ("qwen-code", &["--experimental-acp"]), ("opencode", &["acp"]), ("goose", &["acp"]), ("hermes", &["acp"])];
+pub const ACP_AGENTS: &[(&str, &[&str])] = &[
+ ("gemini-cli", &["--experimental-acp"]),
+ ("qwen-code", &["--experimental-acp"]),
+ ("opencode", &["acp"]),
+ ("goose", &["acp"]),
+ ("hermes", &["acp"]),
+ ("maki", &["acp"]),
+];
+
+/// Agents whose ACP mode takes the backend's model (`cli_model`), and the flag after the ACP
+/// arguments that picks it. Others keep the model they're set to.
+pub const ACP_MODEL_FLAGS: &[(&str, &str)] = &[("maki", "-m")];
+
+/// The arguments after `agent`'s ACP ones that pick `model`; none when its ACP mode isn't known
+/// to take one.
+pub fn model_args(agent: &str, model: Option<&str>) -> Vec<String> {
+ let flag = ACP_MODEL_FLAGS.iter().find(|(id, _)| *id == agent).map(|(_, f)| *f);
+ match (flag, model.map(str::trim).filter(|m| !m.is_empty())) {
+ (Some(flag), Some(model)) => vec![flag.to_string(), model.to_string()],
+ _ => Vec::new(),
+ }
+}
/// The ACP version we speak.
const PROTOCOL_VERSION: u64 = 1;
@@ -753,6 +773,36 @@ mod tests {
assert_eq!(run("other", json!({})).0, "t", "unknown kinds are asked about by title");
}
+ #[test]
+ fn maki_starts_in_acp_mode_with_the_backends_model() {
+ assert_eq!(acp_args("maki"), Some(&["acp"][..]));
+ assert_eq!(model_args("maki", Some(" anthropic/claude-sonnet-4-6 ")), ["-m", "anthropic/claude-sonnet-4-6"]);
+ assert!(model_args("maki", None).is_empty() && model_args("maki", Some(" ")).is_empty());
+ // An agent whose ACP mode isn't known to take a model keeps its own, as before.
+ assert!(model_args("opencode", Some("x/y")).is_empty());
+ }
+
+ /// `maki -m <model> acp` starts with Maki's default model: the flag only counts after `acp`.
+ #[test]
+ fn a_maki_backend_runs_acp_then_its_model_after_its_own_args() {
+ let config = crate::BackendConfig {
+ name: "Maki".into(),
+ kind: crate::BackendKind::AgentCli,
+ model: "maki".into(),
+ base_url: None,
+ ssh_host: None,
+ enabled: true,
+ };
+ let options = crate::BackendOptions {
+ acp: Some(true),
+ cli_model: Some("anthropic/claude-sonnet-4-6".into()),
+ args: vec!["--no-plugins".into()],
+ ..Default::default()
+ };
+ let Some(c) = super::super::acp_for(&super::super::CliSpec::new(config, options, false, None)) else { panic!("Maki speaks ACP") };
+ assert_eq!((c.program.as_str(), c.args.as_slice()), ("maki", &["--no-plugins", "acp", "-m", "anthropic/claude-sonnet-4-6"].map(String::from)[..]));
+ }
+
#[test]
fn stopping_cancels_the_prompt_and_open_questions() {
let mut c = core(None);
diff --git a/crates/ai/src/cli_agents/adapters.rs b/crates/ai/src/cli_agents/adapters.rs
index b2a7763a..d8693d7f 100644
--- a/crates/ai/src/cli_agents/adapters.rs
+++ b/crates/ai/src/cli_agents/adapters.rs
@@ -7,9 +7,11 @@ use super::*;
mod antigravity;
mod hermes;
+mod maki;
mod opencode;
pub use antigravity::Antigravity;
pub use hermes::Hermes;
+pub use maki::Maki;
pub use opencode::OpenCode;
/// What a run's arguments are built from.
@@ -104,10 +106,18 @@ impl Default for AgentAdapters {
}
impl AgentAdapters {
- /// Claude Code, Codex, Gemini CLI, OpenCode, Antigravity and Hermes.
+ /// Claude Code, Codex, Gemini CLI, OpenCode, Antigravity, Hermes and Maki.
pub fn built_in() -> AgentAdapters {
AgentAdapters {
- adapters: vec![Arc::new(ClaudeCode), Arc::new(Codex), Arc::new(GeminiCli), Arc::new(OpenCode), Arc::new(Antigravity), Arc::new(Hermes)],
+ adapters: vec![
+ Arc::new(ClaudeCode),
+ Arc::new(Codex),
+ Arc::new(GeminiCli),
+ Arc::new(OpenCode),
+ Arc::new(Antigravity),
+ Arc::new(Hermes),
+ Arc::new(Maki),
+ ],
}
}
diff --git a/crates/ai/src/cli_agents/adapters/maki.rs b/crates/ai/src/cli_agents/adapters/maki.rs
new file mode 100644
index 00000000..6207d5a2
--- /dev/null
+++ b/crates/ai/src/cli_agents/adapters/maki.rs
@@ -0,0 +1,88 @@
+//! Maki (`maki -p`).
+//!
+//! `-p/--print` is a switch: the prompt is Maki's positional argument, so it goes last. Plain
+//! `maki <prompt>` opens its terminal interface instead of answering.
+//!
+//! Maki lets its file tools write anywhere under its working folder without asking, and in `-p`
+//! nothing can ask. So outside a build its tools that change something are switched off with
+//! `--disallowed-tools` (names it doesn't know are skipped, so an older Maki still runs).
+//! Anything else that would ask first (an MCP server's tools, in subagents too) is refused at once
+//! in `-p`, since nobody can answer, unless the person allowed it in Maki's own permissions.
+//!
+//! Nothing here asks us, so a Clean room build's reads aren't checked: the same gap as every agent
+//! that never asks us, left to the approval decision in the roadmap (R2.2).
+
+use super::*;
+
+pub struct Maki;
+
+/// Maki's tools that change files or run something: writing tools, the shell, and code execution
+/// (its `open()` writes through the write tool, but it can also remove and rename).
+const CHANGES: &str = "write,edit,multiedit,edit_lines,insert_lines,bash,code_execution";
+
+impl AgentAdapter for Maki {
+ fn ids(&self) -> &'static [&'static str] {
+ &["maki"]
+ }
+
+ fn args(&self, cx: &ArgsCx) -> Vec<String> {
+ let mut v = Vec::new();
+ if let Some(m) = &cx.options.cli_model {
+ v.extend(["-m".into(), m.clone()]);
+ }
+ if !cx.builder {
+ v.extend(["--disallowed-tools".into(), CHANGES.into()]);
+ }
+ v.extend(cx.options.args.iter().cloned());
+ v.extend(["-p".into(), format!("{}{}", cx.preamble, cx.prompt)]);
+ v
+ }
+
+ fn required_flags(&self) -> (&'static [&'static str], &'static [&'static str]) {
+ (&["--help"], &["--print"])
+ }
+
+ /// Plain `maki <prompt>` opens the terminal interface; a failed flag check keeps this adapter.
+ fn plain_fallback(&self) -> bool {
+ false
+ }
+
+ fn streams_json(&self) -> bool {
+ false
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn args(builder: bool, options: &BackendOptions) -> Vec<String> {
+ let mcp = McpCommand { command: "craft-anything-cli".into(), args: vec!["mcp".into()], notes: None };
+ Maki.args(&ArgsCx { options, prompt: "make a game", preamble: "PRE ", mcp: &mcp, resume: None, builder, reads_checked: false, question: false })
+ }
+
+ #[test]
+ fn the_prompt_goes_last_after_print_and_the_flags() {
+ assert_eq!(args(true, &BackendOptions::default()), ["-p", "PRE make a game"]);
+ let options =
+ BackendOptions { cli_model: Some("anthropic/claude-sonnet-4-6".into()), args: vec!["--max-turns".into(), "40".into()], ..Default::default() };
+ assert_eq!(args(true, &options), ["-m", "anthropic/claude-sonnet-4-6", "--max-turns", "40", "-p", "PRE make a game"]);
+ }
+
+ #[test]
+ fn outside_a_build_maki_can_only_read() {
+ let a = args(false, &BackendOptions::default());
+ assert_eq!(a, ["--disallowed-tools", CHANGES, "-p", "PRE make a game"]);
+ for tool in ["write", "edit", "multiedit", "edit_lines", "bash", "code_execution"] {
+ assert!(CHANGES.split(',').any(|t| t == tool), "{tool} is switched off");
+ }
+ assert!(!args(true, &BackendOptions::default()).contains(&"--disallowed-tools".to_string()), "a builder keeps its tools");
+ }
+
+ #[test]
+ fn maki_is_registered_and_never_run_plain() {
+ assert!(AgentAdapters::built_in().for_agent("maki").ids().contains(&"maki"), "registered, not the plain adapter");
+ assert_eq!(Maki.required_flags(), (&["--help"][..], &["--print"][..]));
+ assert!(!Maki.plain_fallback() && !Maki.streams_json());
+ }
+}
diff --git a/crates/ai/src/cli_agents/mod.rs b/crates/ai/src/cli_agents/mod.rs
index e6ca4437..7187940b 100644
--- a/crates/ai/src/cli_agents/mod.rs
+++ b/crates/ai/src/cli_agents/mod.rs
@@ -43,6 +43,7 @@ pub const KNOWN: &[(&str, &str, &str)] = &[
("hermes", "hermes", "Hermes Agent"),
("qwen-code", "qwen", "Qwen Code"),
("goose", "goose", "Goose"),
+ ("maki", "maki", "Maki"),
("aider", "aider", "Aider"),
];
@@ -404,6 +405,7 @@ fn acp_for(spec: &CliSpec) -> Option<AcpConversation> {
let program = spec.options.command.clone().unwrap_or_else(|| program_for(&agent));
let mut args = spec.options.args.clone();
args.extend(acp_args.iter().map(|a| a.to_string()));
+ args.extend(acp::model_args(&agent, spec.options.cli_model.as_deref()));
let cwd = spec.project.clone().or_else(|| std::env::current_dir().ok()).unwrap_or_else(std::env::temp_dir);
let mcp = mcp_for(spec, false);
let preamble = spec.preamble.clone().unwrap_or_else(|| crate::prompt::cli_preamble(spec.beginner));
@@ -1175,6 +1177,6 @@ mod tests {
assert!(reg.for_agent("claude").resumes() && !reg.for_agent("codex").resumes() && reg.for_agent("antigravity").resumes());
// Registering an adapter for an existing id replaces that one.
reg.register(Arc::new(EchoAgent));
- assert_eq!(format!("{reg:?}"), r#"["claude-code", "codex", "gemini-cli", "opencode", "antigravity", "hermes", "echo-agent"]"#);
+ assert_eq!(format!("{reg:?}"), r#"["claude-code", "codex", "gemini-cli", "opencode", "antigravity", "hermes", "maki", "echo-agent"]"#);
}
}
diff --git a/crates/ai/src/config.rs b/crates/ai/src/config.rs
index 9d00a2ae..6c851f4d 100644
--- a/crates/ai/src/config.rs
+++ b/crates/ai/src/config.rs
@@ -306,5 +306,7 @@ mod tests {
assert_eq!(one("model = \"x/y\"\ncommand = \"opencode\"\ncli_model = \"z\""), ("opencode".into(), Some("z".into())));
assert_eq!(one("model = \"my-agent\"\ncommand = \"my-agent-cli\""), ("my-agent".into(), None));
assert_eq!(one("model = \"claude-code\""), ("claude-code".into(), None));
+ // Maki named by its program runs Maki's own adapter, not `maki <prompt>` (its terminal interface).
+ assert_eq!(one("model = \"anthropic/claude-sonnet-4-6\"\ncommand = \"maki\""), ("maki".into(), Some("anthropic/claude-sonnet-4-6".into())));
}
}
diff --git a/crates/ai/src/lib.rs b/crates/ai/src/lib.rs
index 3b584822..01b5827f 100644
--- a/crates/ai/src/lib.rs
+++ b/crates/ai/src/lib.rs
@@ -67,7 +67,7 @@ impl BackendKind {
BackendKind::Openai => &[openai::OPENAI_DEFAULT_MODEL],
BackendKind::Openrouter => openai::OPENROUTER_MODELS,
BackendKind::OpenaiCompatible => &[],
- BackendKind::AgentCli => &["claude-code", "codex", "gemini-cli", "opencode", "antigravity", "hermes"],
+ BackendKind::AgentCli => &["claude-code", "codex", "gemini-cli", "opencode", "antigravity", "hermes", "maki"],
}
}
diff --git a/crates/ai/src/tests.rs b/crates/ai/src/tests.rs
index 7c55c84f..a0b14318 100644
--- a/crates/ai/src/tests.rs
+++ b/crates/ai/src/tests.rs
@@ -97,6 +97,17 @@ fn a_coding_agent_test_says_it_only_checked_the_version() {
assert_eq!(serde_json::to_value(&r).unwrap()["version_only"], true, "the CLI's ai test prints it");
}
+/// Every known agent with an adapter of its own is offered when adding a coding agent.
+#[test]
+fn every_agent_with_its_own_adapter_is_offered() {
+ let adapters = cli_agents::adapters::AgentAdapters::built_in();
+ let own: Vec<&str> = cli_agents::KNOWN.iter().map(|(id, _, _)| *id).filter(|id| adapters.for_agent(id).ids().contains(id)).collect();
+ assert!(own.contains(&"maki"), "{own:?}");
+ for id in own {
+ assert!(BackendKind::AgentCli.suggested_models().contains(&id), "{id} isn't offered");
+ }
+}
+
/// #37: doctor asks a local server for its models instead of trusting an open port.
#[test]
fn a_local_server_is_reachable_only_when_it_lists_models() {
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 5b26259c..288c00ed 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -517,7 +517,7 @@ Owner: maintainers · Status: in progress (built; live runs need keys)
### R2.2 More coding agents
Owner: open · Status: in progress
- [x] `AcpConversation`: chat with agents that speak ACP (`cli_agents::acp`; agents and their ACP
- arguments in `ACP_AGENTS`: Gemini CLI, Qwen Code, opencode, goose, Hermes). Opt-in per backend
+ arguments in `ACP_AGENTS`: Gemini CLI, Qwen Code, opencode, goose, Hermes, Maki). Opt-in per backend
(`acp = true` in its options); one agent process per chat, permission requests become
consent questions, sessions continue with `session/load`
- [x] Builder runs over ACP: with `acp = true`, rebuild runs use `AcpConversation`; the agent's
@@ -533,6 +533,24 @@ Owner: open · Status: in progress
- [ ] Say on each adapter, as typed data, what it can be held to (asks us, its own sandbox, nothing),
and have runs act on that, once the decision above is made
- [ ] Check live what Hermes over ACP asks about: whether its file reads reach our approval policy
+- [x] Maki as a coding agent: one message per `maki -p`, and over ACP (`maki acp -m <cli_model>`);
+ run live as an ACP builder (a page to Ready, a follow-up continued with `session/load`, its
+ requests refused unattended with Auto mode off)
+- [ ] Over ACP, a continued session shows the earlier conversation again: `session/load` replays it
+ as `session/update`s, which we show as new; drop updates until the load answers
+- [ ] Over ACP, turns report 0 tokens: the protocol sends only `usage_update` (context used and
+ size). Read real counts where an agent keeps them (Maki: `token_usage` in its session file
+ under `~/.local/state/maki/sessions/`) or say the count is unknown instead of 0
+- [ ] Maki's plain `maki -p` builder doesn't ask us before commands, and in Clean room its reads
+ aren't checked (as with every agent that never asks us): say so in the approval decision
+ above, or run Maki over ACP by default once that passes. Outside a build, tools the person
+ allowed in Maki's own permissions (an MCP server's, or all of them with `always_yolo`) still
+ run; the adapter can't see that config
+- [ ] Maki over ACP writes inside its working folder without a permission request (its built-in
+ rule), and that folder is a build's project folder, so writes to our own records (inbox,
+ manifest) skip the approval policy; `maki acp` takes no tool flags to stop it (0.7.0). Start
+ it in `app/` (paths in the prompt relative to that), or ask Maki for a way to make those
+ writes ask; part of the approval decision above
### R2.3 Website coverage and a better visual metric
Owner: open · Status: done
@@ -670,6 +688,10 @@ What the person asks for comes first, in every kind; the stack table is only the
- [ ] Make: a game whose request names a technology the stack table doesn't know (Phaser, Bevy…)
still needs the default engine installed to start, though the builder is told to use what
was named; ask the person, or let such a game start without an engine
+- [ ] Build check: a page asked for in plain HTML and CSS has nothing to build, but the check
+ only knows Cargo.toml, package.json and engine projects ("No project to build found in
+ app/"), so a builder added a placeholder package.json (`"build": "node -e \"0\""`) to pass;
+ count a static site (an `index.html` in app/) as built
- [x] CLI: after the tool name, `--project` is the tool's own option when it has one
(`rebuild-check --project <folder>`, `project-show --project <folder>`), as `--format` is;
otherwise, and always before the tool name, it's the global investigation folder
diff --git a/docs/STATUS.md b/docs/STATUS.md
index 21617fdf..62d6042f 100644
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@@ -22,7 +22,7 @@ workspace clippy, layers, fmt and the secret scan of all history were clean. Chi
| Auto mode | Settings → Safety, on by default. Builder actions go ahead without asking, except a fixed set that is never done unasked (deleting outside the project, system changes, publishing…); questions get "decide yourself"; asset spending stops at the budget | Unit tests |
| Generated assets | Off until the person turns them on for a game (the switch on Make and on the project, `project_assets_allow`, `rebuild --generate-assets`, saved in craft.json; turning it on without a fal.ai key asks for one); the brief and the asset tools need both that and a key. `assets_image_generate` (Nano Banana Pro by default) and `assets_model_generate` (picture → Tripo P1 low-poly GLB with a face limit) through the person's key for each asset provider (fal.ai today); per-project budget, $5 by default (`[assets] budget_usd` in config.toml); models and prices from the `assets.toml` table (picture model selectable: Nano Banana Pro, FLUX dev or schnell; priced per picture or per megapixel); every call reports its cost | Unit tests; a live 3D generation with a real key (picture, then model) with FLUX dev; Nano Banana Pro not yet run with a real key |
| Claude Code builder | Runs the person's own `claude` in headless mode (Opus 5.5, high effort unless configured) with our MCP server, a permission-prompt tool and `core_person_ask`; preflights for our CLI (a build stops plainly if it's missing or won't start) and sign-in | Argument and stream-parser tests; live preflight; live builder turns; see [claude-code.md](claude-code.md) |
-| Agents over ACP | Opt-in per backend (`acp = true`): Gemini CLI, Qwen Code, opencode and goose in their ACP mode, one agent process per chat or build with our MCP server. In chat, permission requests become consent questions; in builds they go through the same approval policy as Claude Code's (inbox, Auto mode) | Protocol unit tests against scripted agent messages and an approval-policy test; not yet run against a real agent |
+| Agents over ACP | Opt-in per backend (`acp = true`): Gemini CLI, Qwen Code, opencode, goose, Hermes and Maki in their ACP mode, one agent process per chat or build with our MCP server; Maki's ACP mode takes the backend's model (`cli_model`). In chat, permission requests become consent questions; in builds they go through the same approval policy as Claude Code's (inbox, Auto mode) | Protocol unit tests against scripted agent messages and an approval-policy test. Run live with Maki 0.7.0 only (2026-11-02, Linux, headless CLI): a static page built to Ready in 38 s, a follow-up continued the same session with `session/load`, and with Auto mode off its command and tool requests were refused in an unattended run. Turns report 0 tokens over ACP, and a continued session shows the earlier conversation again |
| WASM plugins | With `--features wasm-plugins`: `[[plugins.wasm]]` components exporting `craft-anything:plugin/tools` add tools, and ones exporting `craft-anything:plugin/checks` add checks run after each kind's own (they get the build's file list as JSON) (added, listed, turned on or off and removed in Settings → Plugins or with `plugins_add`/`plugins_remove`/`plugins_list`); no imports, fresh instance per call, fuel and memory limits | Tests with components written in WAT (describe, call, checks, a looping call stopped, imports refused, end to end through the engine); `examples/wasm-plugin-wordcount` built from Rust and loaded |
| Questions and approvals | A file inbox per project; `core_person_ask`, `core_action_approve` and MCP consent requests become cards in the app | Cross-handle round-trip tests, a full approval round trip through the engine |
| Desktop app | Simple mode: sidebar with New project and the project history (kept across restarts); New project either makes something or just looks inside an app or file, a website or a game's files; a Game files screen (a game's archives; pictures from Unreal paks, Unity .assets files and Unity bundles saved as PNG after the person confirms they may unpack the game; uncompressed textures and the block formats DXT1, DXT5 and BC4–BC7), make prompt with picture attachments and, for anything recreated, a Clean room / Deep choice (also in the title bar; in Clean room, Just look inside, Game files, opening a file and the workbench ask for Deep mode instead), project screen (steps with the time spent and the AI cost and tokens of every build, saved in the project's usage.json by the run (a coding agent's figure is shown as an estimate at API prices, not the bill), what the build is on now and its activity as it arrives (kept in `build-activity.log`), pinned builder checklist, feed, question and approval cards, a Continue card when a build was paused or stopped part-way (the app or computer closed; the project shows Interrupted) that carries on the builder's own session instead of starting over, and "It's done" beside Continue or Try again to keep the build as it is (`project_build_finish`), checks with screenshots and the requirements not met yet, the builder's open questions, preview, play, folder, follow-ups while it builds, which Claude Code takes at its next step; Up in the prompt box takes back the last note still waiting). Projects can start in a folder the person picks, whose files are either the app, edited in place, or material to start from (asked, or the answer remembered in Settings), and are listed from any number of folders (`project_folders`, `project_list`, `rebuild --project-folder`). Make says which AI builds ("Built by": automatic, or any AI that can build, by name); a pick stays with the project and builds its later changes. With nothing to build with, Start offers the coding agents found on the computer. Settings → AI turns an AI off or removes it. In the prompt box, Up at the very start and Down at the very end go through earlier prompts when no note is waiting. Questions about a build ("Just ask" under the prompt box, or a message starting with `/btw`, the first slash command; `rebuild_question_ask`) are answered in the conversation, where each folds away and is kept in the project, without a build or a round and changing nothing: Claude Code answers from a read-only copy of the builder's own session. Under each project's prompt box, "Builder's questions: Ask me / Decide yourself" chooses whether the builder's questions come to the person as cards or are decided by the builder, which says what it chose (`project_questions_set`; the default is in Settings and follows Auto mode until picked). Projects can be renamed, duplicated and deleted (right-click in the sidebar, or the project's page; a delete keeps the person's own files). A build can be pinned (Pin this build on its page, or `project_pin_*` from the CLI and MCP): a frozen copy in the project's pinned/ folder (the default) or a light one that shares dependencies and media with the project through hard links (each one's size shown first), opened from the sidebar's collapsible Pinned section (icons with a running dot when folded); a pin or Play runs once per folder unless another copy is asked for, and a start that quits at once says so with its last output. Typed drafts survive a restart. In a narrow window the sidebar folds to icons and the project's details move above its feed; messages float over the screen and errors stay until dismissed. Advanced mode: workbench with every panel wired to real tools, as a screen beside the projects (builds and their questions stay a click away) | UI unit and smoke tests (egui_kittest), offscreen snapshots of every screen |
@@ -79,6 +79,14 @@ against a stand-in server, not yet a real Cutter). Every tool is listed in `docs
runs with `--auto`; Hermes's `-z` turns its approvals off on every run, chats included, so a Hermes
chat isn't limited to analysing and Clean room's approval rule doesn't reach it. Hermes is opt-in
and hasn't been run live here.
+- Maki (`maki -p`, or over ACP with `acp = true`) is offered when adding a coding agent and found by
+ Detect. Over ACP it asks us before commands, our own tools and writes outside its working folder;
+ writes inside that folder (a build's project folder, our own records included) and every read
+ never ask, so the approval policy and Clean room's read rule don't reach those. Plain `maki -p`
+ doesn't ask at all, so a Clean room build's reads aren't checked either; outside a build it runs
+ with its writing tools, shell and code execution switched off, and Maki refuses anything else
+ that would ask (an MCP server's tools, in subagents too) unless the person allowed it in Maki's
+ own permissions. It hasn't been run as a `maki -p` builder here.
- Claude Code is fully wired as a builder; Codex works through its own flags but is unverified on
a real install and doesn't resume; other agent programs get plain text in and out. API-key
backends (Anthropic, OpenRouter, OpenAI, local; Kimi K3 through OpenRouter is offered by Detect; a backend chosen as the Extractor takes a Deep-mode game's own files out into `app/Original/` after the study) build with our own loop and the Build tools,
diff --git a/docs/extending.md b/docs/extending.md
index c15cbf13..90ade445 100644
--- a/docs/extending.md
+++ b/docs/extending.md
@@ -11,7 +11,7 @@ place to add yours. Follow `AGENTS.md` (never crash, layers, external programs t
| A kind of thing to make | `crates/ai/src/rebuild/kinds/` | Implement `TargetKind` (detection score, default stack, brief sections, checks, refine message, 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. |
| 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 dependencies that show a build uses it. A component or styling library is a `[[library]]` entry (name, phrases, the stacks it works with, steps). |
-| 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`. Agents it doesn't know run with the plain adapter. An agent that speaks ACP needs only a row in `cli_agents::acp::ACP_AGENTS` (its id and the arguments that start ACP mode). |
+| 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`. Agents it doesn't know run with the plain adapter. An agent that speaks ACP needs only a row in `cli_agents::acp::ACP_AGENTS` (its id and the arguments that start ACP mode); if its ACP mode takes the backend's model, a row in `ACP_MODEL_FLAGS` too. |
| 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. |
diff --git a/docs/pitfalls.md b/docs/pitfalls.md
index 8edb488f..9773ba48 100644
--- a/docs/pitfalls.md
+++ b/docs/pitfalls.md
@@ -119,6 +119,11 @@ browser outlived the CLI (the job isn't killed when closed) and held the shell's
the command hung and old browsers piled up. Start programs that hand off with `.hands_off()`, and
after a live run check that the command returned and nothing it started is still running.
+**A separate config folder hides the agent's own settings.** To keep a live run from touching the
+real `config.toml`, `XDG_CONFIG_HOME` was pointed at a scratch folder; the agent CLI we start reads
+the same variable, lost its own provider settings, and failed with "unsupported provider". Back up
+`config.toml` and restore it after the run instead, and leave the agent's environment as it is.
+
**A renamed CLI can't start the builder's tools.** To keep a live run's binary from being locked, it
was copied as `cli-r25.exe`; the CLI finds itself by name (`craft-anything-cli`) to start the
builder's MCP server, so Claude Code saw no tools and stopped. Copy it under its own name into a