Using the agent

Prompting

Type a request at the prompt and press Enter, the same way you would with any coding assistant. For example: "find why the login test fails and fix it", or "explain what src/queue.ts does". The agent reads and searches your project, proposes changes, and edits files.

Run free-pi-cli from the project directory you want it to work in.

What the agent can do

The agent is limited to this set of built-in tools:

• read: Read a file
• write: Create or overwrite a file
• edit: Change part of a file
• bash: Run a shell command
• grep: Search file contents
• find: Find files by name
• ls: List a directory

Because bash, write, and edit can change your machine, run free-pi in a project you are comfortable letting it modify, and keep your work under version control.

It also has two free-pi tools that take no arguments:

• free_pi_usage reports your usage. It is the same report as the /usage command.
• free_pi_docs returns a short built-in guide, so you can ask the agent questions about free-pi itself, such as how the allowance or the commands work.

free-pi uses a fixed tool list. If a tool outside it is ever offered to the model, the CLI blocks the call and reports the occurrence to the server.

Keys inside the terminal

The startup screen lists the main key hints:

• Esc interrupts the agent while it is working.
• Ctrl+C clears the input or exits.
• / opens the list of commands. See Commands and flags.
• ! runs a shell command yourself, typed after the !.
• Ctrl+O shows a one-line list of key hints.

Sessions and resuming

The server allows one active CLI session per account at a time. If a previous session is stuck, for example because the terminal was killed or you moved to another machine, run /close-other-session to clear it.

Each run of npx free-pi-cli starts a fresh session.

Switching models

Use /model to open the model picker. See Models and limits.