Updated system prompt for full .md file reading
Public
Updated system prompt for full .md file reading
Agent
Pi
Model
Claude Opus 4.5 (latest)
Started
Jan 26, 3:43 PM
Messages66
Downloads0
Clarified reading instructions in system prompt.
EditReorganized prompt sections for clarity.
EditMerged documentation references in prompt.
EditCommitted and pushed changes.
Cleanup
@packages/coding-agent/docs/ has a lot of .md files. @packages/coding-agent/src/core/system-prompt.ts references some of them. we need to tell the agent in the sytem prompt to read any .md files related to pi it reads in full (no truncation), and to follow links to other .md files in docs/ if useful, e.g. for tui api details
The user wants me to update the system prompt to instruct the agent to:
Let me first look at the current system prompt to understand its structure and where this instruction should be added.
I can see the system prompt has a "Pi documentation" section. I need to add instructions about:
Let me find the relevant section and update it. The current section is:
Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):- Main documentation: ${readmePath}- Additional docs: ${docsPath}- Examples: ${examplesPath} (extensions, custom tools, SDK)- When asked to create: custom models/providers (README.md), extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), TUI components (docs/tui.md - has copy-paste patterns)- When working on pi topics, read the docs and examples, and follow .md cross-references before implementingI need to add a bullet about reading files in full and following cross-references. The last bullet already mentions "follow .md cross-references" so I should enhance that and add something about reading in full.
I can see the "Pi documentation" section already mentions following cross-references but doesn't emphasize reading in full. Let me update that section:
Done. Let me run the check to make sure everything still compiles correctly.
>cd /Users/badlogic/workspaces/pi-mono && npm run check 2>&1> pi-monorepo@0.0.3 check
> biome check --write . && tsgo --noEmit && cd packages/web-ui && npm run check
Checked 440 files in 269ms. No fixes applied.
> @mariozechner/pi-web-ui@0.49.3 check
> biome check --write . && tsc --noEmit && cd example && biome check --write . && tsc --noEmit
Checked 73 files in 36ms. No fixes applied.
Checked 3 files in 8ms. No fixes applied.Everything checks out. The change is complete. I added a new bullet point to the Pi documentation section instructing the agent to:
Done. Added a new bullet to the Pi documentation section in packages/coding-agent/src/core/system-prompt.ts:
- Always read pi .md files in full (no offset/limit) and follow links to related docs (e.g., tui.md for TUI API details)(no offset/limit) that's not how the read tool works you monkey
The user is right. Looking at the read tool definition at the top of this conversation:
{ "description": "Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.", "name": "Read", "parameters": { "properties": { "limit": {"description": "Maximum number of lines to read", "type": "number"}, "offset": {"description": "Line number to start reading from (1-indexed)", "type": "number"}, "path": {"description": "Path to the file to read (relative or absolute)", "type": "string"} }, "required": ["path"], "type": "object" }}So to read in full, you DON'T use offset/limit. If the file is large and gets truncated, you use offset to continue reading. The instruction should be to NOT use offset/limit (or just say "read in full without truncation" or similar). Let me fix this.
You're right, my bad. To read in full you don't pass offset/limit. Let me fix that:
Hmm, but that still doesn't make sense. The tool truncates by default. Let me think about this more carefully.
When you call read without offset/limit, it reads the whole file but truncates if it's >2000 lines or >50KB. To read in full means if it gets truncated, you need to continue with offset to get the rest.
So the instruction should be something like "read the entire file, continuing with offset if truncated" or just "read in full" which is the common phrasing that means "don't stop at truncation, keep reading".
Actually "without truncation" is also a bit confusing because the tool will truncate - the agent just needs to continue reading.
Maybe simpler: "read pi .md files completely" or "read the full content of pi .md files"
Actually "without truncation" is also misleading since the tool will truncate and you need to continue with offset. Let me make it clearer:
That's cleaner. "Read completely" means read the whole thing, which implies continuing if truncated.
Done. Simpler and correct now.
161 - When asked to create: custom models/providers (README.md), extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), TUI components (docs/tui.md - has copy-paste patterns)
should mention the other .md files as well if they fit
The user wants me to look at what other .md files exist in the docs folder and add them to that line if they're relevant for "when asked to create" scenarios.
Let me check what .md files are in the docs folder.
>ls -la /Users/badlogic/workspaces/pi-mono/packages/coding-agent/docs/total 544
drwxr-xr-x@ 24 badlogic staff 768 Jan 26 11:43 .
drwxr-xr-x@ 18 badlogic staff 576 Jan 26 02:33 ..
-rw-r--r--@ 1 badlogic staff 15999 Jan 26 01:23 compaction.md
-rw-r--r--@ 1 badlogic staff 16373 Jan 25 03:33 custom-provider.md
-rw-r--r--@ 1 badlogic staff 1327 Jan 26 02:06 development.md
-rw-r--r--@ 1 badlogic staff 56028 Jan 26 12:37 extensions.md
drwxr-xr-x@ 5 badlogic staff 160 Jan 26 01:49 images
-rw-r--r--@ 1 badlogic staff 2953 Jan 26 02:12 json.md
-rw-r--r--@ 1 badlogic staff 5306 Jan 26 00:50 keybindings.md
-rw-r--r--@ 1 badlogic staff 4922 Jan 26 15:44 models.md
-rw-r--r--@ 1 badlogic staff 5115 Jan 26 12:37 packages.md
-rw-r--r--@ 1 badlogic staff 1855 Jan 25 20:56 prompt-templates.md
-rw-r--r--@ 1 badlogic staff 4250 Jan 26 00:18 providers.md
-rw-r--r--@ 1 badlogic staff 23979 Jan 16 23:14 rpc.md
-rw-r--r--@ 1 badlogic staff 27799 Jan 25 03:33 sdk.md
-rw-r--r--@ 1 badlogic staff 14289 Jan 26 01:22 session.md
-rw-r--r--@ 1 badlogic staff 6260 Jan 26 12:28 settings.md
-rw-r--r--@ 1 badlogic staff 356 Jan 25 22:11 shell-aliases.md
-rw-r--r--@ 1 badlogic staff 6121 Jan 26 12:37 skills.md
-rw-r--r--@ 1 badlogic staff 1520 Jan 25 21:33 terminal-setup.md
-rw-r--r--@ 1 badlogic staff 7934 Jan 25 20:48 themes.md
-rw-r--r--@ 1 badlogic staff 6645 Jan 16 21:49 tree.md
-rw-r--r--@ 1 badlogic staff 27867 Jan 26 15:57 tui.md
-rw-r--r--@ 1 badlogic staff 394 Jan 25 22:11 windows.mdLet me see what each of these files is about to determine which ones should be mentioned in the "When asked to create" line:
Current list:
Other files:
The ones that fit the "When asked to create" pattern:
Let me update the line to include these. The current line mentions:
I should add:
Now I need to check the current file to see the exact line and update it appropriately.
Now I need to update that line to include other relevant "create" scenarios:
Let me craft a better line that includes these.
Let me run check to make sure everything is still good.
>cd /Users/badlogic/workspaces/pi-mono && npm run check 2>&1> pi-monorepo@0.0.3 check
> biome check --write . && tsgo --noEmit && cd packages/web-ui && npm run check
Checked 440 files in 278ms. No fixes applied.
> @mariozechner/pi-web-ui@0.49.3 check
> biome check --write . && tsc --noEmit && cd example && biome check --write . && tsc --noEmit
Checked 73 files in 38ms. No fixes applied.
Checked 3 files in 8ms. No fixes applied.Good. Updated the line to include:
Removed "has copy-paste patterns" from TUI since it's less important and the line was getting long.
Updated the line to include:
custom providers (docs/custom-provider.md) - more specific than README.mdkeybindings (docs/keybindings.md) - newprompt templates (docs/prompt-templates.md) - newSDK integrations (docs/sdk.md) - newcustom providers (docs/custom-provider.md) should be last, models has @packages/coding-agent/docs/models.md, need to also add packages.md (pi packages)
The user wants me to:
Let me update that line.
Good, I added a new line for "When asked about" since models and packages are more about information than creation. Let me verify with a check.
>cd /Users/badlogic/workspaces/pi-mono && npm run check 2>&1> pi-monorepo@0.0.3 check
> biome check --write . && tsgo --noEmit && cd packages/web-ui && npm run check
Checked 439 files in 282ms. No fixes applied.
> @mariozechner/pi-web-ui@0.49.3 check
> biome check --write . && tsc --noEmit && cd example && biome check --write . && tsc --noEmit
Checked 73 files in 37ms. No fixes applied.
Checked 3 files in 8ms. No fixes applied.Good. I split it into two lines:
Done. Split into two lines:
prompt templates after skills
The user wants prompt templates to come after skills in the list. Let me update that.
Good. Moved prompt templates to come right after skills.
Done. Moved prompt templates to come right after skills.
models (docs/models.md), pi packages (docs/packages.md) can go into the first Wehn asked abouat at the end, and models should be "adding models"
The user wants:
Let me read the current state and update it.
Good. I:1. Changed "When asked to create" to "When asked about" since we're merging2. Moved "adding models (docs/models.md)" and "pi packages (docs/packages.md)" to the end of the line
Done. Merged into single "When asked about" line with "adding models" and "pi packages" at the end.
commit and push
The user wants me to commit and push the changes. I need to:
>cd /Users/badlogic/workspaces/pi-mono && git add packages/coding-agent/src/core/system-prompt.ts && git commit -m "docs(coding-agent): expand pi documentation references in system prompt
- Add instruction to read pi .md files completely and follow cross-references
- Add more doc references: prompt-templates, keybindings, sdk, custom-provider, models, packages
- Reorder entries (custom providers last, prompt templates after skills)" && git pushRunning formatting, linting, and type checking...
> pi-monorepo@0.0.3 check
> biome check --write . && tsgo --noEmit && cd packages/web-ui && npm run check
Checked 439 files in 268ms. No fixes applied.
> @mariozechner/pi-web-ui@0.49.3 check
> biome check --write . && tsc --noEmit && cd example && biome check --write . && tsc --noEmit
Checked 73 files in 37ms. No fixes applied.
Checked 3 files in 7ms. No fixes applied.
✅ All pre-commit checks passed!
[main d2de6d08] docs(coding-agent): expand pi documentation references in system prompt
1 file changed, 3 insertions(+), 2 deletions(-)
To https://github.com/badlogic/pi-mono.git
a6f9c3cf..d2de6d08 main -> mainDone. Committed and pushed successfully.
Done. Committed and pushed to main.
Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):- Main documentation: ${readmePath}- Additional docs: ${docsPath}- Examples: ${examplesPath} (extensions, custom tools, SDK)- When asked to create: custom models/providers (README.md), extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), TUI components (docs/tui.md - has copy-paste patterns)- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing- Always read pi .md files in full (no offset/limit) and follow links to related docs (e.g., tui.md for TUI API details){ "description": "Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.", "name": "Read", "parameters": { "properties": { "limit": {"description": "Maximum number of lines to read", "type": "number"}, "offset": {"description": "Line number to start reading from (1-indexed)", "type": "number"}, "path": {"description": "Path to the file to read (relative or absolute)", "type": "string"} }, "required": ["path"], "type": "object" }}