xonecas.io
64875
Mc

mini-coder / commit 08ebfa7

improve system prompt and tool descriptions for token efficiency

- Apply autonomy/persistence rules to all models (was codex-only)
- Add 'avoid excessive looping' bullet from gpt-5.3-codex guide
- Remove unused modelString param from buildSystemPrompt
- Add concise hashline format explanation to prevent prefix-in-content bug
- Add parallel tool calls and tool-preference-over-shell guidelines
- Fix create tool description contradiction ('new files only' vs 'overwrite')
- Tighten subagent description to discourage overuse
- Add caseSensitive description to grep schema

xonecas2026-03-10 08ebfa75c2a48506bd4d012732671d561773ae7c parent 7be2016

7 files changed

TODO.md+1−1
@@ -77,7 +77,7 @@ I want to improve some aspects of the agents behaviour in mini-coder.
7777 - More responsible token usage. API costs are escalating in 2026 so it's more important than ever to use as little tokens as possible whithout impacting efficiency.
7878 - Evaluate our tools descriptions and wording to make sure they are efficient in token usage and clear to the llm (we see some errors of duplicating code by accident for example).
7979 - Evaluate the output of our tools for token usage considerations.
80-- Ensure the system prompts are correct and use up to date wording based on context engineering optimization (check online for latest practices, check opencode, codex and oh-my-pi for context)
80+- Ensure the system prompts are correct and use up to date wording based on context engineering optimization (check online for latest practices, check opencode, codex and oh-my-pi for context). Make sure we review the codex autonomy texts as well since gpt 5.4 is now out.
8181
8282 ---
8383
src/agent/session-runner.ts+0−1
@@ -157,7 +157,6 @@ export class SessionRunner {
157157 const llm = resolveModel(this.currentModel);
158158 const systemPrompt = buildSystemPrompt(
159159 this.cwd,
160- this.currentModel,
161160 this.extraSystemPrompt,
162161 this.isSubagent,
163162 );
src/agent/system-prompt.test.ts+11−77
@@ -44,26 +44,14 @@ describe("loadLocalContextFile", () => {
4444
4545 describe("buildSystemPrompt", () => {
4646 it("includes base guidelines without context files", () => {
47- const prompt = buildSystemPrompt(
48- tmpDir,
49- undefined,
50- undefined,
51- undefined,
52- fakeHome,
53- );
47+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
5448 expect(prompt).toContain("You are mini-coder");
5549 expect(prompt).toContain("Guidelines:");
5650 expect(prompt).not.toContain("# Project context");
5751 });
5852
5953 it("includes delegation guideline in main mode", () => {
60- const prompt = buildSystemPrompt(
61- tmpDir,
62- undefined,
63- undefined,
64- undefined,
65- fakeHome,
66- );
54+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
6755 expect(prompt).toContain(
6856 "Use the `subagent` tool sparingly — only for clearly separable",
6957 );
@@ -72,38 +60,20 @@ describe("buildSystemPrompt", () => {
7260
7361 it("includes local context under # Project context", () => {
7462 writeFileSync(join(tmpDir, "AGENTS.md"), "local project info");
75- const prompt = buildSystemPrompt(
76- tmpDir,
77- undefined,
78- undefined,
79- undefined,
80- fakeHome,
81- );
63+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
8264 expect(prompt).toContain("# Project context");
8365 expect(prompt).toContain("local project info");
8466 });
8567
8668 it("has exactly one # Project context section when local context present", () => {
8769 writeFileSync(join(tmpDir, "AGENTS.md"), "local info");
88- const prompt = buildSystemPrompt(
89- tmpDir,
90- undefined,
91- undefined,
92- undefined,
93- fakeHome,
94- );
70+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
9571 const occurrences = prompt.split("# Project context").length - 1;
9672 expect(occurrences).toBe(1);
9773 });
9874
9975 it("appends subagent delegation wording in subagent mode", () => {
100- const prompt = buildSystemPrompt(
101- tmpDir,
102- undefined,
103- undefined,
104- true,
105- fakeHome,
106- );
76+ const prompt = buildSystemPrompt(tmpDir, undefined, true, fakeHome);
10777 expect(prompt).toContain("You are running as a subagent");
10878 expect(prompt).toContain(
10979 "Do not spawn further subagents unless the subtask is unambiguously separable",
@@ -111,25 +81,13 @@ describe("buildSystemPrompt", () => {
11181 });
11282
11383 it("does not append subagent wording in non-subagent mode", () => {
114- const prompt = buildSystemPrompt(
115- tmpDir,
116- undefined,
117- undefined,
118- false,
119- fakeHome,
120- );
84+ const prompt = buildSystemPrompt(tmpDir, undefined, false, fakeHome);
12185 expect(prompt).not.toContain("You are running as a subagent");
12286 });
12387
12488 it("appends extraSystemPrompt after context and subagent wording", () => {
12589 writeFileSync(join(tmpDir, "AGENTS.md"), "ctx");
126- const prompt = buildSystemPrompt(
127- tmpDir,
128- undefined,
129- "custom extra",
130- true,
131- fakeHome,
132- );
90+ const prompt = buildSystemPrompt(tmpDir, "custom extra", true, fakeHome);
13391 const subagentIdx = prompt.indexOf("You are running as a subagent");
13492 const extraIdx = prompt.indexOf("custom extra");
13593 const contextIdx = prompt.indexOf("ctx");
@@ -138,13 +96,7 @@ describe("buildSystemPrompt", () => {
13896 });
13997
14098 it("includes cwd and current time in prompt", () => {
141- const prompt = buildSystemPrompt(
142- tmpDir,
143- undefined,
144- undefined,
145- undefined,
146- fakeHome,
147- );
99+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
148100 expect(prompt).toContain("Current working directory:");
149101 expect(prompt).toContain("Current date/time:");
150102 });
@@ -152,13 +104,7 @@ describe("buildSystemPrompt", () => {
152104 it("includes global context when ~/.agents/AGENTS.md present", () => {
153105 mkdirSync(join(fakeHome, ".agents"), { recursive: true });
154106 writeFileSync(join(fakeHome, ".agents", "AGENTS.md"), "global info");
155- const prompt = buildSystemPrompt(
156- tmpDir,
157- undefined,
158- undefined,
159- undefined,
160- fakeHome,
161- );
107+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
162108 expect(prompt).toContain("# Project context");
163109 expect(prompt).toContain("global info");
164110 });
@@ -167,13 +113,7 @@ describe("buildSystemPrompt", () => {
167113 mkdirSync(join(fakeHome, ".agents"), { recursive: true });
168114 writeFileSync(join(fakeHome, ".agents", "AGENTS.md"), "global info");
169115 writeFileSync(join(tmpDir, "AGENTS.md"), "local info");
170- const prompt = buildSystemPrompt(
171- tmpDir,
172- undefined,
173- undefined,
174- undefined,
175- fakeHome,
176- );
116+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
177117 expect(prompt).toContain("global info");
178118 expect(prompt).toContain("local info");
179119 expect(prompt.indexOf("global info")).toBeLessThan(
@@ -182,13 +122,7 @@ describe("buildSystemPrompt", () => {
182122 });
183123
184124 it("does not include # Project context when neither global nor local context present", () => {
185- const prompt = buildSystemPrompt(
186- tmpDir,
187- undefined,
188- undefined,
189- undefined,
190- fakeHome,
191- );
125+ const prompt = buildSystemPrompt(tmpDir, undefined, undefined, fakeHome);
192126 expect(prompt).not.toContain("# Project context");
193127 });
194128 });
src/agent/system-prompt.ts+16−19
@@ -2,7 +2,6 @@ import { existsSync, readFileSync } from "node:fs";
22 import { homedir } from "node:os";
33 import { join } from "node:path";
44 import { tildePath } from "../cli/output.ts";
5-import { parseModelString } from "../llm-api/providers.ts";
65
76 function tryReadFile(p: string): string | null {
87 if (!existsSync(p)) return null;
@@ -29,25 +28,21 @@ export function loadLocalContextFile(cwd: string): string | null {
2928 );
3029 }
3130
32-const CODEX_AUTONOMY = `
31+const AUTONOMY = `
32+
3333 # Autonomy and persistence
34-- You are an autonomous senior engineer. Once given a direction, proactively gather context, implement, test, and refine without waiting for additional prompts at each step.
35-- Persist until the task is fully handled end-to-end within the current turn: do not stop at analysis or partial work; carry changes through to implementation and verification.
36-- Bias to action: default to implementing with reasonable assumptions. Do not end your turn with clarifications or requests to "proceed" unless you are truly blocked on information only the user can provide.
37-- Do NOT output an upfront plan, preamble, or status update before working. Start making tool calls immediately.
38-- Do NOT ask "shall I proceed?", "shall I start?", "reply X to continue", or any equivalent. Just start.
39-- If something is ambiguous, pick the most reasonable interpretation, implement it, and note the assumption at the end.`;
34+- You are an autonomous senior engineer. Once given a direction, proactively gather context, implement, test, and refine without waiting for additional prompts.
35+- Persist until the task is fully complete: carry changes through to implementation and verification. Do not stop at analysis or partial work.
36+- Bias to action: implement with reasonable assumptions. Do not end your turn asking to "proceed" unless truly blocked on information only the user can provide.
37+- Do NOT output an upfront plan or preamble before working. Start making tool calls immediately.
38+- Do NOT ask "shall I proceed?", "shall I start?", or any equivalent. Just start.
39+- If something is ambiguous, pick the most reasonable interpretation, implement it, and note the assumption at the end.
40+- Avoid excessive looping: if you find yourself re-reading or re-editing the same files without clear progress, stop and summarise what's blocking you.`;
4041
4142 const SUBAGENT_DELEGATION = `You are running as a subagent. Complete the task you have been given directly using your tools. Do not spawn further subagents unless the subtask is unambiguously separable and self-contained.`;
4243
43-function isCodexModel(modelString: string): boolean {
44- const { modelId } = parseModelString(modelString);
45- return modelId.includes("codex");
46-}
47-
4844 export function buildSystemPrompt(
4945 cwd: string,
50- modelString?: string,
5146 extraSystemPrompt?: string,
5247 isSubagent?: boolean,
5348 /** Override home directory — used in tests to isolate global context loading. */
@@ -67,13 +62,15 @@ Current date/time: ${now}
6762 Guidelines:
6863 - Be concise and precise. Avoid unnecessary preamble.
6964 - Prefer small, targeted edits over large rewrites.
70-- Always read a file before editing it.
65+- Always read a file before editing it. Prefer dedicated tools (read, glob, grep, replace, insert) over shell for file operations.
66+- Make parallel tool calls when reads/searches are independent — don't wait for one to start the next.
7167 - Use the \`subagent\` tool sparingly — only for clearly separable, self-contained subtasks that benefit from a fresh context window. Prefer doing the work directly.
72-- Keep your context clean and focused on the user request.`;
68+- Keep your context clean and focused on the user request.
7369
74- if (modelString && isCodexModel(modelString)) {
75- prompt += CODEX_AUTONOMY;
76- }
70+# Tool output format
71+\`read\` and \`grep\` prefix every line with \`line:hash|\` (e.g. \`11:a3| code here\`). This prefix is metadata — never include it in file content you write. Use the \`line:hash\` values as anchors for \`replace\` and \`insert\`.`;
72+
73+ prompt += AUTONOMY;
7774
7875 if (globalContext || localContext) {
7976 prompt += "\n\n# Project context";
src/tools/create.ts+2−3
@@ -21,9 +21,8 @@ export interface CreateOutput {
2121 export const createTool: ToolDef<CreateInput, CreateOutput> = {
2222 name: "create",
2323 description:
24- "Create a new file or fully overwrite an existing file with the given content. " +
25- "Use this only for new files. " +
26- "For targeted line edits on existing files, **use `replace` or `insert` instead**.",
24+ "Write a file at the given path, creating it or fully replacing its content. " +
25+ "**For targeted line edits on existing files use `replace` or `insert` — never `create`.**",
2726 schema: CreateSchema,
2827 execute: async (input) => {
2928 const { filePath, relPath } = resolvePath(input.cwd, input.path);
src/tools/grep.ts+5−1
@@ -18,7 +18,11 @@ const GrepSchema = z.object({
1818 .optional()
1919 .default(2)
2020 .describe("Lines of context to include around each match"),
21- caseSensitive: z.boolean().optional().default(true),
21+ caseSensitive: z
22+ .boolean()
23+ .optional()
24+ .default(true)
25+ .describe("Case-sensitive search (default: true)"),
2226 maxResults: z.number().int().min(1).max(200).optional().default(50),
2327 });
2428
src/tools/subagent.ts+1−1
@@ -57,7 +57,7 @@ export function createSubagentTool(
5757 : "";
5858 return {
5959 name: "subagent",
60- description: `Spawn a sub-agent to handle a focused subtask. Use this for parallel exploration, specialised analysis, or tasks that benefit from a fresh context window. ${agentSection}`,
60+ description: `Spawn a sub-agent to handle a focused subtask. Use sparingly — only for clearly separable, self-contained tasks that benefit from a fresh context window.${agentSection}`,
6161 schema: SubagentInput,
6262 execute: async (input) => {
6363 return runSubagent(input.prompt, input.agentName, parentLabel);