Skip to content

Commit c82237b

Browse files
Docs: the migration guide covers the npm command, the remote sandbox, the console and going back to 2.x
1 parent f5c4014 commit c82237b

1 file changed

Lines changed: 61 additions & 23 deletions

File tree

‎docs/MIGRATING.md‎

Lines changed: 61 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,37 @@
11
# Migrating to gitagent 3
22

3-
gitagent 3 replaces the TypeScript packages (1.x and 2.x) with one Rust binary. Most agents need no changes. This guide goes through the upgrade step by step and lists the few things that behave differently.
3+
In gitagent 3 the agent runs in one Rust binary. The npm package `@open-gitagent/gitagent` is still how most people install it: it now brings the binary along, and it still provides the `gitagent` command and the TypeScript SDK. Most agents need no changes. This guide goes through the upgrade step by step and lists the few things that behave differently.
44

5-
## 1. Install the binary
5+
## At a glance
66

7-
```sh
8-
curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/scripts/install.sh | sh
9-
gitagent --version
10-
```
7+
| | |
8+
|---|---|
9+
| Agent folders, hooks, schedules, workflows, plugins | Run unchanged |
10+
| The `gitagent` command and its flags | The same, including `-s`/`--sandbox` through npm |
11+
| `query()` and `tool()` in TypeScript | The same |
12+
| Exit codes | No longer always 1 on error ([step 4](#4-update-scripts-that-check-exit-codes)) |
13+
| Unattended runs | Stop after 30 minutes unless you set a limit ([step 5](#5-set-a-time-limit-if-your-unattended-runs-need-longer-than-30-minutes)) |
14+
| The agent's shell | Sandboxed on your machine by default ([step 6](#6-check-what-the-agent-writes-outside-its-folder)) |
15+
| Voice | Not in gitagent 3; stay on 2.x if you need it |
1116

12-
The binary goes into `~/.local/bin`; set `INSTALL_DIR` to put it somewhere else.
17+
## 1. Install gitagent 3
1318

1419
If you installed gitagent with npm, update it the same way:
1520

1621
```sh
1722
npm install -g @open-gitagent/gitagent@latest
23+
gitagent --version # 3.0.0
24+
```
25+
26+
This installs the binary for your platform (Linux x86_64/arm64, macOS arm64/x86_64) as a small extra package, `@open-gitagent/gitagent-<os>-<cpu>`, and a `gitagent` command that runs it. On other platforms, build from source and set `GITAGENT_BIN` to the binary. If you install with `--omit=optional`, the binary package is skipped; set `GITAGENT_BIN`, or use the install script instead.
27+
28+
Without npm, the install script puts the binary in `~/.local/bin` (set `INSTALL_DIR` to put it somewhere else):
29+
30+
```sh
31+
curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/scripts/install.sh | sh
1832
```
1933

20-
This now installs the binary for your platform (Linux x86_64/arm64, macOS arm64/x86_64) and a `gitagent` command that runs it. On other platforms, build from source and set `GITAGENT_BIN`. If you install with `--omit=optional`, the binary package is skipped; set `GITAGENT_BIN`, or use the install script instead.
34+
If you have both, whichever `gitagent` comes first on your `PATH` runs. Only the npm command runs the remote sandbox ([step 8](#8-the-remote-sandbox---sandbox)).
2135

2236
## 2. Check your agent folder
2337

@@ -33,14 +47,18 @@ gitagent validate ./my-agent
3347
gitagent -p "summarise what this agent does" --dir ./my-agent
3448
```
3549

36-
The CLI flags you used before work as they did: `-p`, `-d`, `-m`, `-e`, `--repo`, `--pat`, `--session`, and the console's slash commands.
50+
The command line you used before works as it did:
51+
52+
- **Flags:** `-p`/`--prompt` or the task as plain words, `-d`/`--dir`, `-m`/`--model`, `-e`/`--env`, `-r`/`--repo`, `--pat` and `--session`. `-s`/`--sandbox`, `--sandbox-repo` and `--sandbox-token` run the remote sandbox through the npm command ([step 8](#8-the-remote-sandbox---sandbox)).
53+
- **Subcommands:** `gitagent plugin install|list|enable|disable|remove|init`, with 1.x's `ls`, `rm` and `create`.
54+
- **The console:** `/memory`, `/skills`, `/plugins`, `/exit` and `/quit`. `/tasks` and `/learned` belonged to 1.x's skill learner; they now say what replaces it (lessons, [step 12](#12-what-changed-or-went-away)). `/help` lists the new ones: `/agents`, `/tools`, `/workflows`, `/schedules`, `/new` and `/clear`.
3755

3856
## 4. Update scripts that check exit codes
3957

4058
| Exit code | gitagent 3 |
4159
|---|---|
4260
| 0 | The run ended, including when it ran out of turns or time |
43-
| 2 | Usage or setup error |
61+
| 2 | Usage or setup error, also a flag for a feature that is gone (`--voice`) |
4462
| 3 | The model provider failed |
4563
| 130 | The run was stopped |
4664

@@ -52,31 +70,39 @@ Runs nobody watches (`-p`, schedules, the SDKs) now stop after 30 minutes by def
5270

5371
## 6. Check what the agent writes outside its folder
5472

55-
Outside benchmark runs, the agent's shell now runs in a sandbox. It may write only to the working folder, the output folder, the temp folders and `~/.cache` (and `~/Library/Caches` on macOS). Reading is not restricted. If your agent legitimately writes elsewhere, or a container already isolates it, set:
73+
Outside benchmark runs, the agent's shell now runs in a sandbox on your machine. It may write only to the working folder, the output folder, the temp folders and `~/.cache` (and `~/Library/Caches` on macOS). Reading is not restricted. If your agent legitimately writes elsewhere, or a container already isolates it, set:
5674

5775
```yaml
5876
# gitagent.yaml
5977
sandbox: off # auto (default) | on | off
6078
```
6179
80+
This is separate from the remote sandbox in [step 8](#8-the-remote-sandbox---sandbox), which runs the agent's commands in a cloud VM.
81+
6282
## 7. SDK code
6383
64-
- **TypeScript.** `query()`, `tool()`, hooks, `steer()`, `abort()`, the message types and the `repo` option are unchanged, and tools keep their 1.x names (`cli`, `read`, …). The binary comes with the npm package. `import ... from "@open-gitagent/gitagent/cli"` still runs the command. A `tool()` handler still gets the arguments and an `AbortSignal`, and may return a string, 1.x's `{text, details}` or `{content, isError}`.
65-
- **Other 2.x exports.** 2.x also exported the harness's internals, such as `loadAgent`, `discoverSkills`, `CostTracker`, the schedule, history, compaction and telemetry helpers, and the voice types. The binary does this work now. These names still exist, so imports keep working, but they are marked deprecated, and calling one throws a `GitagentError` that names the replacement (for costs, `q.costs()`; for schedules, `gitagent schedule`).
66-
- **Python.** The new client in `clients/python` has the same shape: `query()`, `tool()`, hooks and an approver, plus `send()`, `steer()`, `abort()` and `end()`.
84+
- **TypeScript.** `query()`, `tool()`, hooks, `steer()`, `abort()`, the message types and the `repo` option are unchanged, and tools keep their 1.x names (`cli`, `read`, …). The binary comes with the npm package; to use another one, set `GITAGENT_BIN` or pass `binary` to `query()`. `import ... from "@open-gitagent/gitagent/cli"` still runs the command. A `tool()` handler still gets the arguments and an `AbortSignal`, and may return a string, 1.x's `{text, details}` or `{content, isError}`.
85+
- **The `sandbox` option** of `query()` and `createSandboxContext()` work as in 2.x ([step 8](#8-the-remote-sandbox---sandbox)).
86+
- **Your own tools in place of the built-in ones.** With `replaceBuiltinTools: true`, the tools you pass to `query()` are the agent's only tools, and one of yours may use a built-in name such as `cli` or `memory`.
87+
- **Other 2.x exports.** 2.x also exported the harness's internals, such as `loadAgent`, `discoverSkills`, `CostTracker`, the schedule, history, compaction and telemetry helpers, and the voice types. The binary does this work now. These names still exist, so imports keep working, but they are marked deprecated, and calling one throws a `GitagentError` that names the replacement (for costs, `q.costs()`; for schedules, `gitagent schedule`; for sessions, `sessionId` with `resume: true`).
88+
- **Python.** The new client in `clients/python` has the same shape: `query()`, `tool()`, hooks and an approver, plus `send()`, `steer()`, `abort()` and `end()`. It needs the binary installed, and has no remote sandbox option.
6789
- **Other languages.** Start `gitagent --ipc` and exchange JSON lines. The README's [SDKs](../README.md#sdks-any-language-over-ipc) section has the full protocol and a complete client in bash.
6890

6991
## 8. The remote sandbox (`--sandbox`)
7092

71-
The remote sandbox works as in 2.x, through the npm command. The agent runs on your machine, so your API keys stay there; its commands and file edits run in an E2B VM with a clone of the repository, which is committed when the VM stops.
93+
The remote sandbox works as in 2.x, through the npm command. The agent runs on your machine, so your API keys stay there; its commands and file edits run in an E2B VM with a clone of the repository, which is committed when the VM stops. It needs the `gitmachine` package, as before:
7294

7395
```sh
7496
npm install -g @open-gitagent/gitagent gitmachine
75-
gitagent --sandbox -p "fix the failing test" # the folder's origin
76-
gitagent -s --sandbox-repo https://github.com/org/app.git # one task per line
97+
gitagent --sandbox -p "fix the failing test" # clones the folder's origin
98+
gitagent -s --sandbox-repo https://github.com/org/app.git # one task per line; exit or Ctrl-D ends
7799
```
78100

79-
`--sandbox-token` (default: `GITHUB_TOKEN` or `GIT_TOKEN`), `--session`, `-d`, `-m`, `-e` and `-p` work with it as before. In the SDK, `query({ ..., sandbox: true })` or `sandbox: { repository, token, template, timeout, autoCommit, envs }` does the same and stops the VM before the iteration ends. In the sandbox the agent uses 2.x's tools (`cli`, `read`, `write`, `edit`, `memory`) instead of gitagent 3's shell, so background sessions and `write_stdin` are not available there. The binary installed with the install script does not run the remote sandbox; it says so and points to the npm command.
101+
- **Flags:** `--sandbox-repo` (default: the folder's `origin`), `--sandbox-token` (default: `GITHUB_TOKEN` or `GIT_TOKEN`), `--session` to continue a session branch, and `-d`, `-m`, `-e` and `-p`. `--repo` cannot be combined with it, as in 2.x.
102+
- **In the SDK:** `query({ ..., sandbox: true })`, or `sandbox: { repository, token, session, template, timeout, autoCommit, envs }`, starts a VM for the session and stops it, committing the work, before the iteration ends. A `SandboxContext` you started yourself with `createSandboxContext()` is used as it is and left running for you to stop.
103+
- **The tools:** in the sandbox the agent uses 2.x's tools (`cli`, `read`, `write`, `edit`, `memory`) instead of gitagent 3's shell, so background sessions and `write_stdin` are not available there. `memory` saves are committed in the VM, and lines over the working layer's `max_lines` move to `memory/archive/`, as before.
104+
- **Errors:** without `gitmachine` or a repository, the command says what is missing and exits with 2.
105+
- **Not here:** the binary from the install script, the Python client and `--ipc` do not run the remote sandbox. The binary says so and points to the npm command.
80106

81107
## 9. Hooks
82108

@@ -86,21 +112,33 @@ Hook scripts get the same JSON and answer the same way. Output that is not an an
86112

87113
`model.constraints` (`temperature`, `max_tokens`, `top_p`, `top_k`, `stop_sequences`) are sent to the providers whose API accepts them. OpenAI's API has no `top_k` or stop sequences, so those two are ignored there with a warning. Current Claude models reject `temperature`, `top_p` and `top_k`, so remove them from Claude agents; `gitagent validate` warns about them.
88114

89-
## 11. What changed or went away
115+
## 11. Telemetry
116+
117+
Set `OTEL_EXPORTER_OTLP_ENDPOINT` to export traces and metrics (OTLP over HTTP/JSON); `OTEL_EXPORTER_OTLP_HEADERS` and `OTEL_SERVICE_NAME` are honoured. 1.x's `GITAGENT_OTEL_ENABLED` is no longer read.
118+
119+
## 12. What changed or went away
90120

91121
| Before | In gitagent 3 |
92122
|---|---|
93123
| `task_tracker`, a searchable task list | `todo`, a plain checklist the agent rewrites whole; the name `task_tracker` still maps to it in tool lists and hooks |
94-
| Online skill learning, which adjusted a skill's confidence after each use | Lessons learned from finished runs (`learning: online` or `gitagent learn`), added to the system prompt; skills are not changed |
124+
| Online skill learning, which adjusted a skill's confidence after each use, with `/tasks` and `/learned` | Lessons learned from finished runs (`learning: online` or `gitagent learn`), added to the system prompt; skills are not changed |
95125
| Every declared tool ran with `sh` unless `runtime` was set | The interpreter is picked by extension (`.py` with `python3`, `.js` with `node`, `.rb` with `ruby`, …); `.sh` still runs under `sh` unless its `#!` line names another shell |
96126
| A plugin's `entry` JavaScript | Plugins contribute tools, skills, hooks and prompt text through files; plugin settings reach scripts as environment variables (`GITAGENT_PLUGIN_CONFIG` holds them all as JSON) |
97-
| The 1.x telemetry adapter (`GITAGENT_OTEL_ENABLED`) | OTLP export: set `OTEL_EXPORTER_OTLP_ENDPOINT`; `GITAGENT_OTEL_ENABLED` is no longer read |
98-
| `--voice`/`-v` and `@open-gitagent/voice` | Not available; the binary prints a one-line note and exits with 2. Keep 2.x if you need voice |
127+
| The 1.x telemetry adapter (`GITAGENT_OTEL_ENABLED`) | OTLP export ([step 11](#11-telemetry)) |
128+
| `--voice`/`-v` and `@open-gitagent/voice` | Not available; the command prints a one-line note and exits with 2. Stay on 2.x if you need voice |
99129

100-
## 12. Optional: new things worth turning on
130+
## 13. Optional: new things worth turning on
101131

102132
- **Parallel work:** `runtime: {parallel_tasks: true}` in `agent.yaml` gives the lead agent the `plan` tool.
103133
- **Lessons:** `learning: online` learns from each finished task into `.gitagent/prompts/lessons.md`; review that file like code.
104134
- **Records:** every run writes `trajectory.json`, `counters.json` and the output of every command to `--out-dir`. `--events jsonl` streams each step as it happens.
105135

136+
## Going back to 2.x
137+
138+
```sh
139+
npm install -g @open-gitagent/gitagent@2
140+
```
141+
142+
Agent folders written for 2.x still work there. If you changed settings to the newer spellings that `gitagent validate` suggests, 2.x may not read them, so keep the old spellings until you no longer need 2.x.
143+
106144
Something not covered here? Open an issue with the output of `gitagent validate` and the command you ran.

0 commit comments

Comments
 (0)