How to drive mini-me from a program

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

# How to drive mini-me from a program

This guide shows how to use a mini-me agent from your own Go, Kotlin or Node.js code: ask it questions, stream its answers, cancel a turn, and decide which tools it may run. It assumes you already have a working agent file (see [Create an agent with `mm init`](create-an-agent.md)) and the `mm` binary.

Your program starts `mm -acp` as a child process and talks to it over ACP, the protocol editors such as Zed use. Nothing changes in mm, so every agent file works, with its tools, hooks, MCP servers and other agents.

## Steps

1. Make `mm` reachable: on the PATH, or name it with `MM_BIN=/path/to/mm`.
2. Pick the client for your language and add it to your project:
   - **Go**: the `minime` module in [`demo.acp.sdk/go/`](../../../demo.acp.sdk/go/README.en.md). Until it is published, point your `go.mod` at it:
     ```bash
     go mod edit -require=minime@v0.0.0 -replace=minime=../path/to/demo.acp.sdk/go
     go mod tidy
     ```
   - **Kotlin** (JDK ≥ 21): the Gradle build in [`demo.acp.sdk/kotlin/`](../../../demo.acp.sdk/kotlin/README.en.md). Until it is published, include it from your `settings.gradle.kts` with `includeBuild("../path/to/demo.acp.sdk/kotlin")`, then depend on `minime:minime:0.1.0` (plus an SLF4J backend such as `org.slf4j:slf4j-nop`, for the SDK's logs).
   - **Node.js** (≥ 20), two clients with the same API:
     - [`demo.acp.sdk/nodejs/`](../../../demo.acp.sdk/nodejs/README.en.md): copy `lib/minime.js`, which has no dependency;
     - [`demo.acp.sdk/nodejs-sdk/`](../../../demo.acp.sdk/nodejs-sdk/README.en.md): built on the official ACP SDK `@agentclientprotocol/sdk`; `npm install ../path/to/demo.acp.sdk/nodejs-sdk`, then `import { Agent } from "minime-sdk"`.
3. Start an agent on your agent file, ask a question, and close it:
   ```go
   agent, err := minime.Start(ctx, minime.Options{Config: "agent.yaml"})
   if err != nil {
   	log.Fatal(err)
   }
   defer agent.Close()

   res, err := agent.Complete(ctx, "What is in this folder?")
   ```
   ```kotlin
   Agent.start(Options(config = "agent.yaml")).use { agent ->
       val result = agent.complete("What is in this folder?")
   }
   ```
   ```js
   import { Agent } from "./lib/minime.js"; // or "minime-sdk"

   const agent = await Agent.start({ config: "agent.yaml" });
   const { text } = await agent.complete("What is in this folder?");
   await agent.close();
   ```
4. To show the answer as it comes, use the stream form instead (`agent.Stream(ctx, prompt)` in Go, the `agent.stream(prompt)` flow in Kotlin, `agent.stream(prompt)` in Node.js) and print the text events.
5. If your agent file has `yolo: false`, give a permission callback, or every tool call is refused:
   ```go
   minime.Options{
   	Config: "agent.yaml",
   	OnPermission: func(_ context.Context, call minime.ToolCall) minime.Decision {
   		if call.Kind == "read" {
   			return minime.Allow
   		}
   		return minime.Reject
   	},
   }
   ```
   ```kotlin
   Options(config = "agent.yaml", onPermission = { call -> if (call.kind == "read") Decision.Allow else Decision.Reject })
   ```
   ```js
   Agent.start({ config: "agent.yaml", onPermission: (call) => call.toolKind === "read" });
   ```

## Variants

- **To stop a long turn**, cancel it: in Go, cancel the `ctx` you passed (for example `context.WithTimeout`); in Kotlin, call `agent.cancel()` from another coroutine; in Node.js, pass `{ signal }` from an `AbortController`. The turn ends with `stopReason: "cancelled"` and the text answered so far. mm drops the unfinished question from the conversation.
- **To start the conversation over** without restarting mm, call `Reset(ctx)` (Go) or `reset()` (Kotlin, Node.js).
- **To work on several things in parallel**, start several agents: each one is its own mm process and runs one turn at a time.
- **To run the tools in another directory** than your program's, set `Cwd` (Go) or `cwd` (Kotlin, Node.js).
- **To see what mm logs** (banner, warnings, `[acp]` lines), set `OnStderr` (Go) or `onStderr` (Kotlin, Node.js).

## See also

- Every option, event and error of each client: [Go](../../../demo.acp.sdk/go/README.en.md), [Kotlin](../../../demo.acp.sdk/kotlin/README.en.md), [Node.js](../../../demo.acp.sdk/nodejs/README.en.md), [Node.js with the ACP SDK](../../../demo.acp.sdk/nodejs-sdk/README.en.md).
- The ACP messages behind the clients: [`demo.acp.sdk/README.en.md`](../../../demo.acp.sdk/README.en.md).
- Confirming tool calls in mm itself: [Confirm tool calls](confirm-tool-calls.md).