Use
Tools
What an agent connected to a project can do, and exactly what each tool takes.
On this page
Project paths are relative to the project root, or to the working copy of the workspace the call names, and confined to it before anything touches the disk. read_file, list_files, grep and command cwd may also use ~/.agents/AGENTS.md and paths under ~/.agents/skills/. Writes cannot. Any other absolute path, or one that climbs out with .., is refused with PATH_ESCAPE.
Which of these a project actually offers is up to its policy: see what a project allows. Tools marked read only change nothing, which is what a project set to read only is left with, and what is never interrupted by a confirmation prompt.
This page is generated from the same definitions the gateway advertises and the executor validates against, so it cannot describe a tool that does not exist or miss an argument that does.
On the account URL, https://exeora.dev/mcp, every tool below also takes an optional project, naming the project to run that one call without changing shared state. A project's own URL has no such argument: it carries its project in the path, and offering a way to name another is exactly what it does not do.
File, command and process tools accept workspace, naming a connected workspace by slug or id, and run on the machine that holds it. Omit it or pass main for the project root at the default location. create_workspace accepts it as an optional source, while detach_workspace and remove_workspace require it as their target. list_git_workspaces and attach_workspace do not take it. The gateway resolves selectors to stable ids and removes the routing field before executor validation. A workspace error never falls back to main.
create_workspace and list_git_workspaces also take where, which names a location of the project: a machine's name, or cloud, as list_projects and list_workspaces name them. Without it a workspace is made at the default location, or beside the workspace named by workspace, which is the checkout it starts from. where is read by the gateway and never sent to a machine, which by then is the one that was chosen. The first workspace on a machine that holds no copy of the repository clones it there first, and one on Exeora Cloud starts an instance, so the call can take a minute or more.
On an instance of Exeora Cloud, run_command and start_command wait while a script of the project is running, for 30 seconds at most, and then go ahead while the script goes on. The tools that read and edit files never wait.
list_workspaces is the gateway's inventory across every location. It lists the project root as main and every other workspace with the location that holds it, and for a workspace on Exeora Cloud the status of its instance. It works while machines are offline. list_git_workspaces asks one machine, requires it to be connected, and includes Git checkouts that are not connected to Exeora.
read_file#
Read file · read only
Read a text file in the project, `~/.agents/AGENTS.md`, or under `~/.agents/skills/`. Output is truncated at 500KB. Use offset/limit for large files; when you need the whole file, continue with offset until complete.
| Argument | Type | What it means |
|---|---|---|
path | string | Project-relative path, or `~/.agents/AGENTS.md` / a path under `~/.agents/skills/`. |
offset optional | integer | 1-based line to start reading from. Omit to start at the beginning. |
limit optional | integer | Maximum number of lines to return. Omit to read to the end. |
list_files#
List files · read only
List a directory or file in the project, `~/.agents/AGENTS.md`, or under `~/.agents/skills/`. Lists one level by default; set recursive to walk subdirectories, and glob to filter (for example '**/*.ts'). Includes dotfiles. Recursive listings respect .gitignore and always skip .git and node_modules. Output is truncated to 1000 entries.
| Argument | Type | What it means |
|---|---|---|
path optional | string | Directory or file to list. Defaults to the project root. |
recursive optional | boolean | Walk subdirectories. Defaults to false. |
glob optional | string | Only return entries matching this glob, e.g. '**/*.ts'. |
grep#
Search file contents · read only
Search a directory or file for a regular expression. Paths may be project-relative, `~/.agents/AGENTS.md`, or under `~/.agents/skills/`. Returns matching lines with file paths and 1-based line numbers. Respects .gitignore and always skips .git and node_modules. Output is truncated to 200 matches, and long lines to 500 characters.
| Argument | Type | What it means |
|---|---|---|
pattern | string | Regular expression to search for. |
path optional | string | Directory or file to search. Defaults to the project root. |
glob optional | string | Restrict the search to files matching this glob. |
caseInsensitive optional | boolean | Ignore case. Defaults to false. |
maxResults optional | integer | Maximum matches to return (max 200). |
edit_file#
Edit file
Edit a file by exact text replacement. oldString must match a unique region of the file, if it appears more than once the edit is refused, so include surrounding lines to disambiguate rather than retrying. Returns a unified diff of what changed.
| Argument | Type | What it means |
|---|---|---|
path | string | Path relative to the project root. Must stay inside the project. |
oldString | string | Exact text to replace. Must match the file byte for byte and must appear exactly once, include surrounding lines to make it unique. |
newString | string | Replacement text. |
write_file#
Write file
Write content to a file, creating it if it does not exist and overwriting it entirely if it does. Parent directories are created automatically. Prefer edit_file for changes to an existing file, so the rest of it is not at risk.
| Argument | Type | What it means |
|---|---|---|
path | string | Path relative to the project root. Must stay inside the project. |
content | string | Full contents to write. Overwrites any existing file. |
apply_patch#
Apply a multi-file patch
Apply several file operations in one call: create, update (unique text replacement), replace (whole file), delete, or move. Checked before anything is written; if any operation cannot run, none of them do. At most 20 operations and 1000KB. Prefer this over repeated edit_file when more than one file must change together.
| Argument | Type | What it means |
|---|---|---|
operations | array | File operations to apply together, all or nothing (max 20). Combined contents must stay within 1000KB. |
list_git_workspaces#
List Git workspaces · read only
List every Git workspace of this repository on one of the user's machines, including ones that are not connected to Exeora. Returns absolute local paths so one can be passed to attach_workspace. Requires that machine to be online; list_workspaces is the inventory of connected workspaces across every location and works offline.
| Argument | Type | What it means |
|---|---|---|
where optional | string | Location to ask: a machine name or `cloud`. Defaults to the project's default. |
create_workspace#
Create workspace
Create a workspace: a branch with a working copy of its own, in one of the project's locations. `where` chooses the location, a machine name or `cloud`; without it the default location is used. Omit the routing workspace to base it on the project root's HEAD, or name a connected workspace to start from that checkout, beside it. The first workspace on a machine clones the repository there, and one on Exeora Cloud starts a machine, so this can take a minute. Always use this tool rather than executing raw git commands.
| Argument | Type | What it means |
|---|---|---|
branch | string | Branch to create or reuse in the new workspace. |
from optional | string | Git ref to base a new branch on. Cannot be used with reuseExistingBranch. |
reuseExistingBranch optional | boolean | Use an existing local branch instead of creating one. Defaults to false. |
name optional | string | Display name. Defaults to the branch. |
slug optional | string | Stable URL-safe selector. Derived from the branch by default. |
where optional | string | Location to create it in: a machine name or `cloud`, from list_projects. Defaults to the project's default location. |
attach_workspace#
Attach workspace
Connect an existing Git workspace to Exeora without taking ownership of it. Pass exactly one absolute path or exact branch; use list_git_workspaces to discover candidates.
| Argument | Type | What it means |
|---|---|---|
path optional | string | Absolute path of an existing Git workspace. Pass exactly one of path or branch. |
branch optional | string | Exact branch checked out in an existing Git workspace. Pass exactly one of branch or path. |
name optional | string | Display name for the connected workspace. |
slug optional | string | Stable URL-safe selector. Derived automatically by default. |
detach_workspace#
Detach workspace
Disconnect a workspace from Exeora without changing or deleting the Git checkout. The MCP routing workspace argument is required and names the workspace to detach.
remove_workspace#
Remove workspace
Disconnect and physically remove a workspace. Refuses uncommitted changes unless force is true, and on Exeora Cloud also work that was never pushed, since the machine is its only copy. Keeps the branch unless deleteBranch is true. The MCP routing workspace argument is required. Always use this tool rather than executing raw git commands.
| Argument | Type | What it means |
|---|---|---|
force optional | boolean | Remove even when the workspace has uncommitted changes. Defaults to false. |
deleteBranch optional | boolean | Also delete the local branch with Git's safe branch -d. Defaults to false. |
run_command#
Run command
Run a shell command on the user's machine, in the project or under `~/.agents/skills/`. Returns stdout, stderr and the exit code. Output is truncated to the last 200KB. The command is killed, with everything it started, after 60s by default and at most 300s. Stdin is closed, so a command that waits for input exits rather than hanging.
| Argument | Type | What it means |
|---|---|---|
command | string | Shell command to run inside the project. |
cwd optional | string | Project-relative, or under `~/.agents/skills/`. Defaults to the project root. |
timeoutMs optional | integer | Wall-clock budget in milliseconds (default 60000, max 300000). |
start_command#
Start a long-running command
Start a command in the project or under `~/.agents/skills/` and return immediately with a handle, for anything that outlives a single call: a dev server, a watch task, a long test run. Read its output with get_command_output and stop it with kill_command. It keeps running until it exits or is killed, but dies with the connection to Exeora, so nothing is left running once nobody is watching. Use run_command for anything that finishes on its own.
| Argument | Type | What it means |
|---|---|---|
command | string | Shell command to start inside the project. |
cwd optional | string | Project-relative, or under `~/.agents/skills/`. Defaults to the project root. |
get_command_output#
Read a command's output · read only
Read output from a process started with start_command, continuing from a cursor. Returns at most 100KB per call, along with whether the process is still running and its exit code if not. Only the last 256KB is kept, so output is reported as skipped rather than silently lost if you read too slowly.
| Argument | Type | What it means |
|---|---|---|
processId | string | Handle returned by start_command. |
cursor optional | integer | Where to read from, as returned by the previous call. Omit to read from the start. |
send_command_input#
Write to a command's input
Write to the standard input of a process started with start_command, for one waiting on an answer. Appends a newline unless told otherwise.
| Argument | Type | What it means |
|---|---|---|
processId | string | Handle returned by start_command. |
data | string | Written to the process's stdin exactly as given. |
newline optional | boolean | Append a newline. Defaults to true, since most prompts wait for one. |
kill_command#
Stop a command
Stop a process started with start_command, along with everything it started. Reports killed: false when it had already exited, which is not an error.
| Argument | Type | What it means |
|---|---|---|
processId | string | Handle returned by start_command. |
list_skills#
List agent skills · read only
List Agent Skills available on this machine: `~/.agents/skills/` and `.agents/skills/` in the project. Returns name, description, source and the path to pass to read_file. Call once near the start of a session; when a description matches the task, read_file that path and follow it. Project skills override user skills with the same name.
Choosing a project#
Two tools are answered by the gateway and never reach a machine, so they work with every machine offline and no project policy applies to them. list_projects exists only on the account URL, where one connection covers several projects and a caller needs to see the valid targets. It shows each project with its repository and the locations it lives in, by the names where takes, and the state of each. list_workspaces is on both URLs. On a project's own URL it takes no project.
A repository that lives nowhere is listed too, with no locations and machine set to nowhere. Nothing can serve a call to it until it has a location again. create_workspace with where set to cloud gives it one. Exeora Cloud in state no instance is the default location with no instance for the project root: the next call to the project root makes it and is answered with EXECUTOR_WAKING, to be sent again in about a minute.
With one project granted, there is nothing to choose and calls may omit project. With more, every executor tool call must carry a project slug or id. The target belongs to that call, so two conversations in the same client can work in different projects without moving each other.
list_workspaces#
List workspaces · read only
List a project's workspaces: the project root, as `main`, and every other branch that has a working copy, with the location that holds each. Pass a project slug or id when this connection reaches more than one project.
| Argument | Type | What it means |
|---|---|---|
project optional | string | The project's slug, or its id. Slugs are unique within an account. |
list_projects#
List projects · read only · account URL only
List the projects this connection can reach, with the locations each one lives in: the user's machines and Exeora Cloud. When more than one project is listed, every other tool call must name its project by slug or id.
Reading the manual#
One more, on both URLs, taking no arguments and reaching no machine.
get_agent_prompt#
Get the Exeora agent prompt · read only
Exeora's own guidance for working as a coding agent on someone's machine: how to search, edit and run things with these tools, and what a refusal from the project's policy means. Read it before your first tool call in a session, and follow it alongside your own instructions.
It returns a constant from the gateway, so it answers with the machine asleep and no project policy applies to it. The same text arrives as the coding_agent prompt, and a shorter form of it in the handshake. See the agent prompt.