You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c82237b
Browse filesBrowse the repository at this point in the historyBrowse files
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.
4
4
5
-
## 1. Install the binary
5
+
## At a glance
6
6
7
-
```sh
8
-
curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/scripts/install.sh | sh
| 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 |
11
16
12
-
The binary goes into `~/.local/bin`; set `INSTALL_DIR` to put it somewhere else.
17
+
## 1. Install gitagent 3
13
18
14
19
If you installed gitagent with npm, update it the same way:
15
20
16
21
```sh
17
22
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
18
32
```
19
33
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)).
21
35
22
36
## 2. Check your agent folder
23
37
@@ -33,14 +47,18 @@ gitagent validate ./my-agent
33
47
gitagent -p "summarise what this agent does" --dir ./my-agent
34
48
```
35
49
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`.
37
55
38
56
## 4. Update scripts that check exit codes
39
57
40
58
| Exit code | gitagent 3 |
41
59
|---|---|
42
60
| 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`)|
44
62
| 3 | The model provider failed |
45
63
| 130 | The run was stopped |
46
64
@@ -52,31 +70,39 @@ Runs nobody watches (`-p`, schedules, the SDKs) now stop after 30 minutes by def
52
70
53
71
## 6. Check what the agent writes outside its folder
54
72
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:
56
74
57
75
```yaml
58
76
# gitagent.yaml
59
77
sandbox: off # auto (default) | on | off
60
78
```
61
79
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
+
62
82
## 7. SDK code
63
83
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.
67
89
- **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.
68
90
69
91
## 8. The remote sandbox (`--sandbox`)
70
92
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:
72
94
73
95
```sh
74
96
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
77
99
```
78
100
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.
80
106
81
107
## 9. Hooks
82
108
@@ -86,21 +112,33 @@ Hook scripts get the same JSON and answer the same way. Output that is not an an
86
112
87
113
`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.
88
114
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
90
120
91
121
| Before | In gitagent 3 |
92
122
|---|---|
93
123
| `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 |
95
125
| 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 |
96
126
| 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 |
| `--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 |
99
129
100
-
## 12. Optional: new things worth turning on
130
+
## 13. Optional: new things worth turning on
101
131
102
132
- **Parallel work:** `runtime: {parallel_tasks: true}` in `agent.yaml` gives the lead agent the `plan` tool.
103
133
- **Lessons:** `learning: online` learns from each finished task into `.gitagent/prompts/lessons.md`; review that file like code.
104
134
- **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.
105
135
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
+
106
144
Something not covered here? Open an issue with the output of `gitagent validate` and the command you ran.
0 commit comments