Tools
The model works through tools. Each call shows in the client: the file it reads or edits, the command it runs.
The built-in tools #
| Tool | What it does |
|---|---|
read_file | read a text file, from a line offset, limit lines (2000 by default, at most 5000) and at most 27000 characters |
write_file | create or replace a file; missing folders are made |
edit_file | replace old_string with new_string; it must occur once, unless replace_all |
glob | list the files whose path matches a pattern such as **/*.py |
grep | find the lines that match a regex, in the files a glob picks |
bash | run a command with bash in the session folder |
todo_write | keep a todo list for a task of several steps: each call gives the whole list, at most 100 items of at most 500 characters, each pending, in_progress or completed and one in progress at most; the clients show it, the session keeps it, and a compaction gives it back to the model |
apply_patch | add, delete and change files with one patch, in the format of Codex; offered on the OpenAI Responses API only |
Skills add activate_skill (Skills), MCP servers add their own tools (MCP), and an extension can add more. Which calls ask before they run is on Approvals and security.
The model sees at most 30000 characters of a tool's output; the rest is cut, with a note that says how long it was.
Profiles #
A profile decides which tools the model of a session sees. Pick one for a new session with --profile NAME, or change it with /profile NAME between turns (/profile alone lists them; while a turn runs the change is refused). The session keeps its profile across a restart, a /tree move and a fork. There are two built in:
build, the default: every tool;plan:read_file,glob,grep,todo_writeandactivate_skill, with a note in the system prompt to change nothing. Nobash, no writes, no MCP tools.
A profile is a file NAME.md in ~/.config/finn/profiles/ ($XDG_CONFIG_HOME/finn/profiles/), or in .finn/profiles/ of a trusted project, which wins over yours. A file named build.md or plan.md replaces the built-in one, so a trusted project may replace plan; a project file that replaces a profile is a warning the clients show. NAME is lowercase letters, digits, - and _: another .md file there (a README.md, a link out of the folder) is skipped with a warning.
---
description: Reads and plans, changes nothing
tools_allow: [read_file, grep, glob, todo_write, "mcp__github__*"]
model: anthropic/claude-sonnet-4-5
thinking: high
---
Plan the change. Do not edit files.descriptionsays what the profile is for.tools_allowshows only the tools it names, andtools_denyall but those; set one of them, or neither for every tool. A*matches any text, somcp__github__*covers one MCP server. An emptytools_allowshows no tool, with a warning.model([PROVIDER/]NAME) andthinking(low,medium,highordefault) change the session's model and thinking level when the profile is chosen; a--model,--provideror/modelgiven then wins, and a later profile without them keeps the session's. A project's profile stays on the session's provider: its wholemodelis a model name there.- The text after the front matter goes after the system prompt.
A file that does not load (an unknown key, both lists) fails only its own name: choosing it is an error with the file and the key, and the server warns about it when it starts. A name in a list that no tool has is a warning the clients show. A saved session whose profile is gone or broken stays closed: it shows no tool and refuses its turns. It opens again with /profile NAME, or on a restart once the file is back and loads.
A profile only hides tools from the model: a call to a hidden one is refused, and the approval rules still decide on the calls of the tools it shows. A profile never allows what a rule denies. A !command you type is yours: a profile does not limit it.
The session folder #
The file tools reach only files whose real path is inside the session folder: a .. or a link that leads out is refused. read_file also reads the files of a skill the session can load. glob and grep never follow a link.
An apply_patch call is checked whole before any file changes. When a step fails, every file goes back as it was.
bash #
bash runs the command in its own process group, in the session folder, with no input. It times out after 2 minutes by default (timeout_ms, at most 10 minutes), and its output is cut at 1 MiB.
The command gets only a few variables of the server's environment (PATH, HOME, USER, LANG, TERM, TMPDIR, SHELL and some more), so the keys of your providers are not in it.
Bash is not a sandbox. The command runs as you, and can do what you can:
- It can still read the server's environment, keys included:
/proc/$PPID/environshows it to a process of the same user. - A timeout or a stop kills the process group; a command that leaves it (
setsid) outlives them. - The paths a call names are checked before it runs, not while it runs.
To keep the model in, run Finn in a container or a sandbox (Approvals and security).
Code mode #
Code mode is on by default: the run_script tool, where the model writes a short Python script that calls the tools as plain functions (read_file(path="a.txt")). The script runs in Monty, pydantic's Python sandbox. Each call from the script goes through the same checks and approvals as a direct call; a denied call raises PermissionError. Only what the script prints and its last value go back to the model.
The Monty worker is FINN_MONTY (a Monty 1.6.0 binary you trust: its hash is not checked), else the pinned Monty 1.6.0, fetched from PyPI at the first script (never at start) into ~/.cache/finn with its sha256 checked. Where no Monty is pinned for the machine and FINN_MONTY is not set, run_script is not offered. The worker runs once (--version) before it is kept: one that cannot run here (a musl system, say) is not installed. A failed fetch is not tried again for 10 minutes. The cached worker is used only while ~/.cache/finn and its monty-1.6.0 folder are yours, no one else can write them, and the worker is a file, not a link. The worker runs with an empty environment, so it never sees your API keys.
finn --no-codemode (also finn chat, finn serve and finn server start or restart) or FINN_CODE_MODE=0 turns code mode off. It is set when the server starts: when the running server's code mode is not the one you ask for, the client says so in one line, and finn server restart (with --no-codemode to turn it off) applies it.