5 Your first agentic session — the four tools
You can run pi both interactively and non-interactively against your local model, you understand the four built-in tools, and you can prove for yourself that the agent really executes them.
5.1 The whole agent in four tools
pi gives the model exactly four built-in tools:
| Tool | What it does |
|---|---|
read |
Read a file’s contents |
write |
Create or overwrite a file |
edit |
Make a surgical change to a file |
bash |
Run a shell command |
That is the entire surface. There is no separate “search”, “todo”, “plan”, or “browser” tool. The model composes everything from these four (you can bash your way to grep, git, python3, and so on). Chapter 1 explains the philosophy; here we just use it.
5.2 Two ways to run
Interactive (terminal user interface, TUI):
pi --provider lmstudio --model 'qwen3-coder-30b-a3b-instruct'You get a chat-style terminal UI; type a request and watch pi read, write, edit, and run commands. Exit with Ctrl+C.
Non-interactive (one-shot), ideal for scripting and for trying things out:
pi -p --offline --provider lmstudio --model 'qwen3-coder-30b-a3b-instruct' \
"Create fib.py that prints the first 10 Fibonacci numbers, then run it with python3."-p/--print processes the prompt and exits. --offline keeps everything local.
5.3 A verified first task
Running the command above in an empty directory produced fib.py on disk:
a, b = 0, 1
for _ in range(10):
print(a)
a, b = b, a + b…and the correct output 0 1 1 2 3 5 8 13 21 34. The file appearing on disk is proof that the write tool fired, not just that the model described a file.
5.4 Proving the agent really runs commands
A healthy scepticism: how do we know bash executed, rather than the model pretending to show output? Ask for something the model cannot possibly know, a fact about your machine, and have it written to disk:
pi -p --offline --provider lmstudio --model 'qwen3-coder-30b-a3b-instruct' \
"Use the bash tool to run exactly: uname -m > proof.txt && sysctl -n hw.model >> proof.txt && cat proof.txt — then tell me what proof.txt contains."On the test machine proof.txt then contained:
arm64
Mac16,5
Those are this host’s central-processing-unit (CPU) architecture and hardware model, values the model has no way to fabricate. Their presence on disk is conclusive evidence that the local model drove pi’s bash tool for real. It is the same uncheatable proof pattern that verified LM Studio’s tool-calling in Section 2.3, and any other tool-capable model you register in Chapter 4 can be checked the same way (bigger models just take longer to load first; see Chapter 8).
5.5 A safety word before you go further
By design, pi does not prompt before each tool call: built-in tools read, write, edit, and run shell commands with your user’s full permissions. There is no sandbox. That is what makes one-shot mode so smooth, but it also means you should run pi in directories you trust and treat untrusted repository content as you would any code you are about to execute. Chapter 6 shows how to constrain behaviour with AGENTS.md, and Chapter 8 links pi’s own security notes.
5.6 Handy input syntax
@path/to/fileinjects a file’s contents into your prompt.!commandruns a shell command and includes its output in your prompt.- Piped stdin is merged into the prompt:
cat README.md | pi -p "Summarize this".
- Re-run the Fibonacci task interactively (
pi --provider lmstudio --model qwen3-coder-30b-a3b-instruct) and watch each tool call scroll by. Which of the four tools does it use? - Restrict pi to a single tool with
--tools readand ask it to change a file. What happens, and why? - Use
@to feed pi one of this book’s.qmdfiles and ask it to summarize the chapter.
The task typically uses
writeto createfib.pyandbashto run it withpython3; if the model revises the file it may also fireedit. The conclusive sign isfib.pyappearing on disk with the correct output0 1 1 2 3 5 8 13 21 34, proving thewriteandbashtools actually fired rather than the model merely describing them.With
--tools readthe model has only thereadtool available, so it cannot create or modify the file: there is nowriteoredittool in its surface to call. It will typically read the file and report that it cannot change it (or describe the change in prose only), and no file on disk is altered. This is the tool surface acting as a guard rail, useful given that pi otherwise runs tools with your full permissions and no sandbox.Prefix the path with
@to inject the file’s contents into your prompt, for example:pi -p --offline --provider lmstudio --model 'qwen3-coder-30b-a3b-instruct' \ "Summarize this chapter: @05_first_session.qmd"pi reads the named
.qmdfile’s text into the prompt and the model returns a summary. Any chapter file works; the summary quality depends on the local model you chose.