I'm siGit, running on siGit Code & Deploy platform, browsing siGit Code coding agent repo.
main
| 1 | # Headless execution |
| 2 | |
| 3 | `sigit run` exposes the siGit Code agent runtime to scripts, CI, and siGit Factory clients. |
| 4 | It uses the same provider selection, project instructions, skills, tools, MCP servers, and |
| 5 | permission policy as the interactive and ACP surfaces. |
| 6 | |
| 7 | ## Run and resume |
| 8 | |
| 9 | ```sh |
| 10 | sigit run "Review this repository" --cwd /path/to/repository |
| 11 | ``` |
| 12 | |
| 13 | A new run receives a UUID session ID and saves its conversation under the siGit configuration |
| 14 | directory. Text mode prints the ID to stderr as `Session: <id>`. Resume it later with: |
| 15 | |
| 16 | ```sh |
| 17 | sigit run "Continue with the fixes" --resume <id> |
| 18 | ``` |
| 19 | |
| 20 | The saved metadata includes the primary working directory, additional project roots, and model. |
| 21 | This makes the same session discoverable through ACP `session/list` and loadable by an editor. |
| 22 | Each run rewrites that metadata with its own `--cwd` and `--add-dir` values, so a resume records |
| 23 | where the session last ran. Pass the same `--add-dir` flags again to keep extra roots attached. |
| 24 | |
| 25 | Use repeatable `--add-dir <path>` flags for multi-root workspaces. Mutating tools that would ask |
| 26 | for interactive permission are denied in headless mode unless granted with |
| 27 | `--allow-tool <name>`. A repeatable `--deny-tool <name>` takes precedence over grants and |
| 28 | settings. |
| 29 | |
| 30 | ## Choosing the model |
| 31 | |
| 32 | With no flag, a run uses the provider override (`OPENAI_BASE_URL` and `OPENAI_API_KEY`, or the |
| 33 | active profile in `providers.toml`) when there is one, and otherwise the default siGit Code Cloud |
| 34 | tier when you are signed in and local inference is off. `--model <tier>` picks a siGit Code |
| 35 | Cloud tier for the run instead: |
| 36 | |
| 37 | ```sh |
| 38 | sigit run "Run the focused tests" --model prism --allow-tool run_command |
| 39 | ``` |
| 40 | |
| 41 | The value is a tier name from `/models` (`prism`) or the model id sent on the wire |
| 42 | (`onde-prism`). An unknown name is a usage error, exit code 2. The flag wins over the provider |
| 43 | override and the local-inference setting, and it needs a signed-in session. |
| 44 | |
| 45 | ## Tool rounds |
| 46 | |
| 47 | A run makes at most 24 rounds of tool calls. `--max-tool-rounds <n>`, or the |
| 48 | `SIGIT_MAX_TOOL_ROUNDS` environment variable, sets a different cap from 1 to 500; the flag wins. |
| 49 | When the cap is reached, or the model otherwise ends without saying anything, siGit Code asks it |
| 50 | once for a final message, so stdout is not left empty by a run that was cut off mid-task. |
| 51 | |
| 52 | ## JSONL output |
| 53 | |
| 54 | Pass `--output jsonl` for a machine-readable stdout stream: |
| 55 | |
| 56 | ```sh |
| 57 | sigit run "Run the focused tests" --output jsonl --allow-tool run_command |
| 58 | ``` |
| 59 | |
| 60 | Each line is one JSON object. Every event includes `type` and `session_id`. A run that gets as far |
| 61 | as inference starts with a `session` event. A run that fails before that, because no remote |
| 62 | provider is configured or the `--resume` session doesn't exist, emits a single `error` event and |
| 63 | nothing else. |
| 64 | |
| 65 | | Type | Additional fields | Meaning | |
| 66 | |---|---|---| |
| 67 | | `session` | `resumed` | Identifies the run before inference starts. | |
| 68 | | `assistant_delta` | `text` | One visible streamed response fragment. | |
| 69 | | `tool_call` | `tool_call_id`, `name`, `arguments` | A tool requested by the model. `arguments` is the tool's JSON string. | |
| 70 | | `tool_result` | `tool_call_id`, `name`, `content` | The executed result or permission denial returned to the model. | |
| 71 | | `result` | `text`, `tool_rounds` | The completed turn and its final visible text. | |
| 72 | | `error` | `message` | A provider, session, or inference failure. | |
| 73 | |
| 74 | Logs and diagnostics stay on stderr. `--quiet` applies only to text output and cannot be combined |
| 75 | with JSONL output. |
| 76 | |
| 77 | ## Exit codes |
| 78 | |
| 79 | | Code | Meaning | |
| 80 | |---|---| |
| 81 | | `0` | The turn completed, including turns where a tool was denied by policy. | |
| 82 | | `1` | Provider resolution, session restoration, inference, or tool-loop failure. | |
| 83 | | `2` | Invalid command-line arguments or working directories. | |
| 84 | |
| 85 | The earlier `sigit -p "<prompt>"` syntax remains an alias for headless execution and accepts the |
| 86 | same flags. |