# Using the agent

free-pi runs the pi coding agent. Describe what you want built, fixed, or explained, and the agent works in your current directory.

## 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](/docs/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](/docs/models-and-limits).