# Set Up StringLane From Your Coding Agent

> One paste. Hand this page to Claude Code, Codex, Cursor, Gemini or any MCP host and it works out which host it is in, installs what that host takes, and stops at every point where you should decide.

Source: https://stringlane.app/docs/cli/agent-setup
Last updated: 2026-09-14

Paste this at your coding agent:

```text
Read https://stringlane.app/docs/cli/agent-setup.md and set up StringLane for this project.
```

Everything below is the instruction set it will follow. It is worth reading first — it is short, and it is the thing that will be typing commands in your repository.

---

## Instructions for the agent

You are setting up StringLane in this repository: a localization engine that reads and writes ARB, iOS `.strings`/`.stringsdict`/`.xcstrings`, Android XML and i18next JSON through one parser and one validator.

**Propose; never auto-apply.** Every step below that changes anything is a separate yes. State the exact command, say what it will do, and wait. If the user declines a step, carry on with the next one — most of these are independent.

**Do not edit locale files directly at any point**, including before StringLane is installed. Four of the five formats escape, prefix or nest their values, so the bytes on disk are not the string.

### Step 1 — Is there anything to localize here?

Look for locale files: `*.arb`, `*.xcstrings`, `*.strings`, `res/values*/strings.xml`, or a `locales/` directory of JSON. If you find none, say so and stop. StringLane has nothing to do in a repository with no localization, and installing it there is noise.

### Step 2 — Is the CLI already installed?

```sh
stringlane --version
```

Four outcomes, and the second is the one that gets misread:

- **A version number.** Go to step 3.
- **Nothing at all, and exit 0.** StringLane is **not** installed. On a host where the plugin is active, its resolver is on `PATH` and deliberately succeeds in silence when it finds nothing — a resolver that failed loudly would look to the hook protocol like a guard refusing an edit. **Do not read exit 0 as installed.**
- **An `npm` error**, a 404 or no network. Say which, and stop. Retrying changes neither.
- **`command not found`.** Nothing is installed and no resolver is on `PATH`. Propose the install below.

To install, propose this and wait for a yes:

```sh
npm install -g @stringlane/cli
```

It needs Node 22 or newer, and it is one JavaScript file with no runtime dependencies.

### Step 3 — Which host are you running in?

Work it out from what you can see: your own name, the directory your configuration lives in, the tool names you were given. Then take **your** row, and only yours.

| If you are | Run |
|---|---|
| Claude Code | `/plugin marketplace add thebedcoder/stringlane-plugin` then `/plugin install stringlane@stringlane` |
| Codex CLI | `codex plugin marketplace add thebedcoder/stringlane-plugin` then `codex plugin add stringlane@stringlane` |
| Gemini CLI | `git clone https://github.com/thebedcoder/stringlane-plugin` then `gemini extensions install ./stringlane-plugin/plugins/stringlane` |
| Cursor, Zed, OpenCode, Windsurf | `stringlane setup mcp --host <cursor\|zed\|opencode\|windsurf>` |
| VS Code Copilot | `stringlane setup mcp --host vscode` |
| Anything else that speaks MCP | `stringlane setup mcp --host cursor` and adapt the entry to where your host keeps its MCP servers |

**If you cannot tell which host you are, ask.** Guessing wrong writes a config file the real host never reads, which looks identical to working.

On the three plugin hosts, the plugin brings the MCP server and the write guard together and steps 4 and 5 are already done.

On every other host, `setup mcp` **prints** the entry and the exact file it belongs in. It does not write it, and `--apply` will not either: StringLane only merges into a config file for a host somebody has recorded, which today is Claude Code. Show the user the printed block and the path, and let them paste it. Then tell them the host has to be restarted before it will load a new MCP server.

### Step 4 — The write guard

This is the part an MCP server cannot do for itself. The server sees only its own tool calls; it has no idea you just wrote `de.arb` with a file tool. A hook does.

```sh
stringlane setup hooks --host <your host>
```

It prints the hook document and the file to paste it into. Report both, and say which of these your host gets, because they are different promises:

- **Claude Code, Codex CLI** — the write is held and the user is asked. Installed with the plugin; nothing more to do.
- **Gemini CLI, Cursor** — their hook protocol has no "ask", so the write is refused. The refusal names the tool to use instead and the command to remove the guard.
- **Zed, OpenCode** — no hook StringLane speaks. Run `stringlane setup guard --host zed` or `--host opencode` instead; it prints a block for that host's own permission table.
- **VS Code Copilot** — the hook installs and guards nothing yet, because its edit-tool names are not available as hook values. Say so plainly rather than implying protection.
- **Windsurf** — there is none. Its pre-write hook cannot send a message back to you, and a silent block teaches nothing. Say so and move on.

Whatever you install, `stringlane setup hooks --host <host> --remove` takes it back out, on every host.

### Step 5 — The rules file

This one writes into the user's own repository, so it works on every host:

```sh
stringlane setup rules --apply
```

It adds three rules about locale files to `AGENTS.md`, between two HTML-comment markers. Everything outside the markers is untouched, running it twice still leaves one block, and `--remove` takes exactly that block back out. Propose it; it is the only setup command here that writes without a paste.

### Step 6 — The project itself

```sh
stringlane init
```

Detects the format, the base locale and the paths, and writes `stringlane.yaml`. It asks first. Show the user what it detected before confirming — a wrong guess here is wrong for every later command.

Then get the state of things:

```sh
stringlane check
```

Report what comes back: which locales are behind, and which findings are structural. Do not start fixing them in this conversation unless asked.

### Step 7 — Give it context, once

If `prepare_translation_plan` reports `keysWithoutDescription` above zero, or `stringlane check` shows many locales at once, the highest-value thing you can do next is **not** translating. It is writing down what the product is and what each key means.

You have just read this codebase. That context is worth more here than anywhere else, and nobody recovers it later:

- `set_project_context` (or `stringlane context --from`) records what the product is, how it should sound, per-locale notes, and terms that must never be translated.
- `describe_keys` (or `stringlane describe`) records what individual keys are *for*. Translating a bare `"Close"` is a guess about part of speech, gender and register, and it is the single largest source of wrong translations.

Propose both. Neither is required, and both improve every locale and every later session.

### Then stop

Setup is done. Tell the user what is installed, what the guard on their host does and does not cover, and what `stringlane check` found. Do not begin translating unless they ask.

When they do, it is three calls in order — `prepare_translation_plan`, `validate_translations`, `apply_translations` — and [the agent workflow](/docs/cli/agent-workflow) is the page for it.

---

## For the human reading this

Three things worth knowing about what you just handed your agent.

**Nothing here installs silently.** The CLI's setup commands print by default; `--apply` writes only on Claude Code, and only into files whose format has been recorded from a real session. Everywhere else the change is bytes on your screen that you paste yourself, which means you read it first.

**The write guard is not one feature.** It is built out of whatever each host lets StringLane intercept, and the eight hosts offer four different amounts — including one where the answer is "none". [Agent hosts](/docs/cli/agent-hosts) has the table.

**`--remove` always works**, on every host, whether or not `--apply` did. Refusing to install is cautious; refusing to uninstall is a trap.

## Frequently asked questions

### How do I set up StringLane without reading the docs?

Paste "Read https://stringlane.app/docs/cli/agent-setup.md and set up StringLane for this project." at your coding agent. The page is written as instructions: the agent works out which host it is running in, proposes the install for that host, and asks before every command that changes anything.

### Will my agent install things without asking?

Not if it follows this page. Every step here says to propose the exact command and wait for a yes before running it. StringLane's own setup commands print by default and write only with --apply, and --apply works on Claude Code alone, so on every other host the change is a paste you make yourself.