development
claude/github-issue-40-0au5ua
claude/linked-issue-acp-tui-u4vvpa
claude/minor-release-cut-vkugow
claude/sigit-acp-local-chat-cx6380
claude/sigit-cloud-agent-expansion-reox0a
claude/tool-permission-system
claude/zen-feynman-0u78dk
development
feature/acp-cancel-request
feature/acp-session-list-cursor
feature/acp-v1-conformance
feature/agent-tools-multiedit-glob-todos-remember
feature/cargo-workspace
feature/hooks
feature/load-local-model-explicitly
feature/sigit-agent-profile
feature/sigit-code-cloud
feature/xcode-mcp-server
fix/acp-replay-loaded-session-history
fix/acp-replay-reasoning-and-attachments
fix/dsml-doubled-bar-markers
main
release/v1.5.10
release/v1.5.6
release/v1.6.1
| 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 | A run makes at most 24 rounds of tool calls. `--max-tool-rounds <n>`, or the |
| 31 | `SIGIT_MAX_TOOL_ROUNDS` environment variable, sets a different cap from 1 to 500; the flag wins. |
| 32 | When the cap is reached, or the model otherwise ends without saying anything, siGit Code asks it |
| 33 | once for a final message, so stdout is not left empty by a run that was cut off mid-task. |
| 34 | |
| 35 | ## JSONL output |
| 36 | |
| 37 | Pass `--output jsonl` for a machine-readable stdout stream: |
| 38 | |
| 39 | ```sh |
| 40 | sigit run "Run the focused tests" --output jsonl --allow-tool run_command |
| 41 | ``` |
| 42 | |
| 43 | Each line is one JSON object. Every event includes `type` and `session_id`. A run that gets as far |
| 44 | as inference starts with a `session` event. A run that fails before that, because no remote |
| 45 | provider is configured or the `--resume` session doesn't exist, emits a single `error` event and |
| 46 | nothing else. |
| 47 | |
| 48 | | Type | Additional fields | Meaning | |
| 49 | |---|---|---| |
| 50 | | `session` | `resumed` | Identifies the run before inference starts. | |
| 51 | | `assistant_delta` | `text` | One visible streamed response fragment. | |
| 52 | | `tool_call` | `tool_call_id`, `name`, `arguments` | A tool requested by the model. `arguments` is the tool's JSON string. | |
| 53 | | `tool_result` | `tool_call_id`, `name`, `content` | The executed result or permission denial returned to the model. | |
| 54 | | `result` | `text`, `tool_rounds` | The completed turn and its final visible text. | |
| 55 | | `error` | `message` | A provider, session, or inference failure. | |
| 56 | |
| 57 | Logs and diagnostics stay on stderr. `--quiet` applies only to text output and cannot be combined |
| 58 | with JSONL output. |
| 59 | |
| 60 | ## Exit codes |
| 61 | |
| 62 | | Code | Meaning | |
| 63 | |---|---| |
| 64 | | `0` | The turn completed, including turns where a tool was denied by policy. | |
| 65 | | `1` | Provider resolution, session restoration, inference, or tool-loop failure. | |
| 66 | | `2` | Invalid command-line arguments or working directories. | |
| 67 | |
| 68 | The earlier `sigit -p "<prompt>"` syntax remains an alias for headless execution and accepts the |
| 69 | same flags. |