# Project config

> The .rexa/config.json file, with toolchain pins and palette actions for a project.

A project can carry a `.rexa/config.json` file in its folder. Commit it to share the setup with everyone who opens the repository in Rexa. Rexa reloads the file when it changes.

```json [.rexa/config.json]
{
  "toolchains": {
    "python": "api/.venv",
    "typescript": "bundled"
  },
  "actions": [
    { "label": "Test", "command": "cargo test --workspace", "mode": "new" },
    { "label": "Dev server", "icon": "globe", "command": "npm run dev", "mode": "reuse" }
  ]
}
```

Each worktree reads its own copy of the file. A subfolder project reads the file in that subfolder, not the repository root.

## toolchains

Pins the toolchain each language server uses, and what terminals and agents get on `PATH`. Keys are `typescript`, `python`, `node`, `rust` and `go`.

| Value                     | Uses                                                          |
| ------------------------- | ------------------------------------------------------------- |
| `automatic` or `project`  | The nearest toolchain Rexa finds in the project.              |
| `bundled`                 | The copy shipped with Rexa (TypeScript).                      |
| A name, such as `.venv` or `20.11.0` | The detected candidate with that name.             |
| A path                    | That toolchain. Relative paths are relative to the repository; `~/` expands. |

A value that matches nothing falls back to automatic. Order of precedence, highest first:

1. A choice made in the status bar picker for that server.
2. `toolchains` in `.rexa/config.json`.
3. `lsp.toolchains` in [Settings](/docs/customize/settings).
4. Automatic detection.

`toolchains` is read from `.rexa/config.json` only.

## actions

Each action becomes a command palette entry (<Kbd>⌘</Kbd> <Kbd>⇧</Kbd> <Kbd>P</Kbd>) named by its `label`. Picking it runs the command in the worktree with `$SHELL -lic`. Picking it again while it runs stops it.

<FieldGroup>
  <Field name="label" type="string" required>Name in the palette.</Field>
  <Field name="command" type="string" required>Shell command to run.</Field>
  <Field name="mode" type="'new' | 'reuse' | 'background'">Where output goes: a new terminal tab, the action's existing tab, or no tab. Defaults to the `run.mode` setting.</Field>
  <Field name="icon" type="string">A Lucide icon name. Defaults to a play icon.</Field>
  <Field name="id" type="string">Stable id. Defaults to the label in lowercase-dash form.</Field>
</FieldGroup>

<Callout type="caution">
  Actions are deprecated and will be replaced. Set `"mode": "new"` or `"reuse"`: in background mode the output has nowhere visible to go.
</Callout>

VS Code `tasks.json` files are not read.