@sigitcodereview / sigit
Code Commits Issues Pulls Cloud Agent CI/CD
main
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
md 538 lines 40.7 KB
Rendered Raw
1 # AGENTS.md
2
3 This file provides guidance to AI coding agents when working with code in this repository.
4
5 ## What this is
6
7 `sigit` ("siGit Code") is a single Rust binary: a local-first AI coding agent that runs LLM
8 inference on-device (via the `onde` crate / GGUF models) or against a hosted/OpenAI-compatible
9 endpoint. It exposes itself two ways from the *same* binary, chosen at startup by whether stdin
10 is a TTY:
11
12 - **ACP mode** (stdin not a TTY): speaks the Agent Client Protocol over stdio for editor
13 integration (Zed, VS Code ACP Client). Cross-platform.
14 - **Interactive terminal mode** (stdin is a TTY): a full-screen ratatui chat UI. **Unix-only** —
15 it relies on fd redirection to keep logs out of the TUI, so Windows gets ACP mode only.
16
17 Before the TTY/ACP split, `main` also dispatches the account subcommands `sigit login`,
18 `sigit logout`, `sigit whoami` (see `src/main.rs` `main()`).
19
20 ## Working in this repo
21
22 **IMPORTANT — branch naming:** Prefix every working branch with `feature/` (new functionality)
23 or `fix/` (bug fixes) — never a tool- or agent-name prefix like `claude/`. Name the branch after
24 the *changes it contains*, as a short, descriptive, kebab-case slug that is self-explanatory
25 from the name alone (e.g. `feature/tool-permission-system`, `fix/glob-mtime-sort`), never after
26 a task, ticket, or session id (not `feature/task-q003hm`).
27
28 **IMPORTANT — pull request target:** Always open pull requests against the `development` branch,
29 never `main`. `main` is release-only; `development` is where day-to-day work integrates, and the
30 release merge (see the `sigit-code-release` skill) is the one thing that ever puts commits on
31 `main`.
32
33 This rule needs help to hold, because the repository's default branch is `main`: both
34 `gh pr create` and the GitHub web form pre-select it, so a PR lands on the wrong base unless the
35 base is passed explicitly. Pass it every time, and check that it took:
36
37 ```sh
38 gh pr create --base development --head <branch>
39 gh pr view <number> --json baseRefName
40 ```
41
42 Retargeting a PR that was opened against `main` costs nothing before it merges:
43 `gh pr edit <number> --base development`. After it merges it costs real work — the change sits on
44 `main` while `development`, which the next release is cut from, does not have it, and someone has
45 to carry it back by hand. PR #65 went in that way.
46
47 **IMPORTANT — branch off `development`:** Start every working branch from the latest
48 `origin/development`. Exception: when new work *depends on* a feature branch that has not merged
49 yet (e.g. it builds on tools or APIs that branch introduces), it may be stacked on top of that
50 branch instead. When stacking: merge the base PR into `development` first, then rebase the
51 stacked branch onto `development` before opening its pull request, so each PR shows only its own
52 commits.
53
54 **IMPORTANT — run CI before pushing:** Run the full CI gate locally and confirm it is green
55 *before* pushing a branch or opening a pull request — never push work that fails these:
56
57 ```sh
58 cargo fmt -- --check # formatting
59 cargo clippy --tests -- -D warnings # lint (warnings are errors)
60 cargo test --locked # tests
61 ```
62
63 ## Agent assets layout
64
65 `.agents/` is the canonical home for agent assets; every other agent path in
66 the repo is a symlink into it, never a copy:
67
68 - `.agents/AGENTS.md` — this file, the project instructions. The root
69 `AGENTS.md` and `CLAUDE.md` are symlinks to it, so agents.md-standard tools,
70 Claude Code, and sigit itself (via `src/instructions.rs`, which prefers
71 `AGENTS.md` over `CLAUDE.md` in the same directory and therefore reads it
72 once) all load the same content. Edit this file; never replace the root
73 symlinks with real files.
74 - `.agents/skills/` — all project skills. `.claude/skills` is a symlink to it,
75 which is how both Claude Code and sigit itself (via `src/skills.rs`) discover
76 them. Add new skills under `.agents/skills/<name>/SKILL.md`, never as real
77 files under `.claude/`.
78
79 ## Build / test / lint
80
81 ```sh
82 cargo build # debug build
83 cargo build --release # release binary at target/release/sigit
84 cargo run # launches interactive TUI (stdin is a TTY)
85 cargo test # CI runs: cargo test --locked --target <target>
86 cargo clippy --tests -- -D warnings # CI gate: clippy is -D warnings on all 4 targets
87 cargo fmt -- --check # CI gate (edition 2024)
88 ```
89
90 CI (`.github/workflows/ci.yml`) runs fmt + clippy + test across four targets:
91 `aarch64-apple-darwin`, `x86_64-apple-darwin`, `x86_64-unknown-linux-gnu`,
92 `x86_64-pc-windows-msvc`. Clippy is `-D warnings`, so warnings fail the build.
93
94 Run a single test: `cargo test <test_name>`.
95
96 ## Critical platform constraint: `#[cfg(unix)]` dead code
97
98 The interactive client is `#[cfg(unix)]`-only. The `InferenceBackend` seam (`backend.rs`) and
99 provider resolution (`provider.rs`) are consumed by both the interactive client and the ACP
100 server, but several of their items are reached only through the Unix-only interactive paths, so
101 the dead-code lint is suppressed *on non-Unix targets only*.
102
103 Consequence: code can pass clippy on macOS/Linux but fail on the Windows target (or vice versa).
104 When touching `backend.rs`, `provider.rs`, or the interactive path, keep the `cfg` gates intact —
105 don't "fix" an unused-warning by deleting code that's live on Unix.
106
107 ## Architecture
108
109 The agent loop is backend-agnostic. The flow: a turn (messages + tool specs) goes to an
110 `InferenceBackend`, which returns assistant text and/or tool calls; the loop executes tools and
111 feeds results back. Neither the loop nor ACP/TUI surfaces depend on a concrete backend.
112
113 - **`src/main.rs`** — entry point, mode dispatch, the full ACP `Agent` impl (session lifecycle:
114 new/load/fork/prompt/cancel, config options, slash-command advertisement), and the `SYSTEM_PROMPT`.
115 ACP session state owns its roots, conversation, and selected model even though the process has
116 one working directory and one live backend slot; activating a thread parks and restores all
117 three. A thread on an HTTP backend keeps a backend of its own (`InferenceBackend::fresh`,
118 `SessionState::remote`), so its turn can wait on the endpoint while another thread is
119 installed. Unknown session ids are rejected instead of silently borrowing the active thread's
120 cwd. Prompt cancellation takes no lock, which lets a client cancel a turn whatever it holds.
121 `session/load` and `session/resume` share `restore_session`; the only difference is that
122 resume must not replay the history as `session/update`. `session/close` is the one place a
123 `SessionState` is dropped. It runs in two halves: `begin_close` signals the session's turn
124 from the dispatch loop (the turn holds the session's lock, so the signal cannot wait for it) and
125 marks the id in `closing_sessions`, which makes `handle_prompt` cancel a prompt that was
126 still queued; `handle_close_session` then runs under the session and workspace locks and
127 removes the state, the permission grants and the background commands
128 (`tools::kill_session_tasks`). It leaves `session_store` alone, so a closed thread still lists
129 and reopens. The
130 `SYSTEM_PROMPT` bakes in smbCloud-specific context the agent should use when the repo is clearly
131 smbCloud, and stay general otherwise.
132 - **`src/backend.rs`** — the `InferenceBackend` trait and neutral types (`ToolSpec`, `ToolCall`,
133 `ToolResult`, `TurnResult`). Two impls: `LocalBackend` (on-device via `onde::ChatEngine`) and
134 `OpenAiBackend` (any OpenAI-compatible HTTP endpoint). A `BackendError` is user-facing: the
135 ACP prompt handler passes it to the client verbatim and the editor puts it in an error banner,
136 so `describe_api_error` unwraps the OpenAI `{"error":{"message":…}}` envelope and shows that
137 message on its own, falling back to the status only when there is nothing to unwrap. An
138 endpoint can also fail *after* the response is open, reporting it as a `data:` frame holding
139 the same envelope; that frame has no `choices`, so `consume_stream` has to check for it
140 explicitly or it parses as an empty chunk and the turn ends looking like an empty answer.
141 `TurnResult::finish` carries the endpoint's `finish_reason` up to the loop, and
142 `stop_reason_for` in `main.rs` turns it into the ACP stop reason: the tool-round cap is
143 `max_turn_requests`, `length` is `max_tokens`, `content_filter` is `refusal`. ACP defines a
144 refusal as a turn the next prompt will not include, so `handle_prompt` restores the history
145 it snapshotted before the turn instead of only relabelling the response.
146 The round that reaches the cap (24, or `SIGIT_MAX_TOOL_ROUNDS`) is followed by one forced
147 text reply with no tools. The model cannot see that the tools are gone, so
148 `round_cap_note` is appended to that round's last tool result, and the turn always closes
149 with `round_cap_stop_message`. Without both, the thread stops on the model announcing a
150 step that never runs (issue #120).
151 Some models write tool calls into content as text; `src/inline_tool_calls.rs` recovers the
152 well-formed ones. A block that doesn't parse (or never closes) is dropped from both the reply
153 and history, and `OpenAiBackend::complete` retries once with a note telling the model the call
154 didn't run. Leaving the raw block in history makes the model invent `<function_results>` later.
155 What that scanner lets through then goes through `src/harness_markup.rs`, which removes
156 markup the model makes up in the harness's shape (issue #122): a `<system_warning>`-style
157 block (any `system_*`/`system-*` tag) is dropped whole, from the reply and the history, and
158 other underscore-named tags like `<Option_Picker>` lose the tags but keep their text. Code is
159 never touched, and an opening tag only counts at the start of a line, since prose writes
160 placeholders like `<repo_url>` the same way. It has to run after the inline-call scanner,
161 because `<tool_call>` matches its underscore rule.
162 `src/repetition.rs` guards the same stream against a reply that degenerates into a loop over a
163 tiny vocabulary (issue #123): a window of 200 words with at most 40 distinct ones, fenced code
164 excepted, makes `consume_stream` stop reading, truncate the text to where the loop began (so
165 history never holds the junk), tell the user, and finish with `FinishReason::Repetition`
166 (`EndTurn` in ACP). `complete` then retries once with `REPETITION_RETRY`, like the malformed
167 tool call retry. Only the streaming path is guarded; `consume_json` and `LocalBackend` are not.
168 Image attachments: ACP fixes `promptCapabilities.image` for the whole connection, while the
169 model can change on any turn, so the capability is always advertised and the decision is made
170 per prompt. `InferenceBackend::accepts_images` answers for the active model (on-device: no;
171 remote: `provider::model_accepts_images`, which reads the hard-coded `IMAGE_TIERS` for
172 `onde-*` ids and says yes for a user's own endpoint). `images_for_turn` in `main.rs` either
173 passes the images to `send_message_with_images` or drops them with a note to the user and a
174 bracketed note to the model. A message with images is stored in history as OpenAI content
175 parts and stays that way; `OpenAiBackend` strips the images per request (`without_images`)
176 when its model cannot read them, which is what makes a mid-thread switch to a text-only tier
177 safe. Read history text through `backend::message_text`, never `content.as_str()`.
178 `IMAGE_TIERS` mirrors onde-cloud's `IMAGE_CANDIDATES`; update both together.
179 Audio attachments take the same path (`promptCapabilities.audio`, `accepts_audio`,
180 `audio_for_turn`, `without_audio`), sent as OpenAI `input_audio` parts. No cloud tier
181 takes audio, because onde-cloud drops `input_audio` parts when it parses a request, so
182 `provider::model_accepts_audio` says no for every `onde-*` id and yes for a user's own
183 endpoint. If onde-cloud ever routes audio, give it a tier table like `IMAGE_TIERS`.
184 - **`src/provider.rs`** — decides *which* backend serves inference. Resolution order, first match
185 wins: (1) override via `OPENAI_BASE_URL`+`OPENAI_API_KEY` or active profile in
186 `~/.config/sigit/providers.toml`; (2) siGit Code Cloud when logged in; (3) on-device.
187 - **`src/tools.rs`** — agent tool schemas + execution: `read_file`, `create_directory`,
188 `list_directory`, `search_files`, `glob`, `read_website`, `create_file`, `edit_file`,
189 `multi_edit`, `delete_file`, `run_command`, `write_todos`, `remember`. Add a tool in both the
190 spec list (`all_tools`) and the execute `match` (`execute_tool`). `run_command` also enforces
191 commit attribution: when a command creates a new commit that lacks the
192 `Co-Authored-By: siGit Code` trailer (`commit_co_author_trailer()`, which reads
193 `siGit Code v<version>-<acp|tui|headless>` from the surface `main` sets via `set_surface`), it amends the trailer in —
194 unless the commit already exists on a remote, which is never rewritten. Every child process it
195 spawns (`spawn_shell`, the `git` helpers, and `hooks.rs`) sets `stdin` to null and never
196 inherits it: in ACP mode sigit's stdin is the JSON-RPC pipe from the editor, so a command that
197 reads stdin both blocks forever and eats the client's next request, wedging the session past
198 any timeout. On Unix the shell also leads its own process group so the timeout kills the whole
199 tree, and stdout/stderr are drained on threads while the command runs — waiting first and
200 reading after deadlocks as soon as the output outgrows the pipe buffer. Also owns the `task`
201 tool: a nested agent loop in a fresh conversation, offered only when `subagent_available()`
202 (a subagent factory is registered — see `register_subagent_factory_for` in `main.rs`; on-device
203 registers a `None`-returning factory since onde has a single shared history). A subagent's
204 toolset is a hard-gated read-only allow-list (`SUBAGENT_TOOL_NAMES`) that is never expanded by a
205 configurable subagent type (see `src/subagents.rs`) — only ever narrowed — so a `.sigit/agents/*.md`
206 file can't grant itself `edit_file`/`run_command` and bypass the permission system. Also owns
207 `web_search`: a thin native wrapper around the official MCP server's Brave-Search-backed
208 `web_search` tool (`mcp__sigit__web_search`, implemented server-side in `sigit-si`'s
209 `WebSearchService` + `Mcp::Tools::WebSearch`), offered only when that MCP tool was actually
210 discovered (i.e. the user is signed in to siGit Code Cloud — see `web_search_available`).
211 Wrapping it natively rather than leaving it as a raw `mcp__*` tool matters for two reasons:
212 `permissions::classify` treats every `mcp__*` tool as mutating (an "ask" prompt on every call),
213 while `web_search` is read-only like `read_website`; and the raw delegate name is filtered out
214 of the assembled tool list (`is_web_search_delegate`) so the model sees one clean option, not
215 two names for the same tool. Execution still forwards verbatim to `mcp::call_tool` — no second
216 HTTP/JSON-RPC implementation.
217 - **`src/skills.rs`** — [Agent Skills](https://agentskills.io) support. Discovers skill
218 folders (each with a `SKILL.md`: YAML frontmatter `name` + `description`, then Markdown
219 instructions) from `.sigit/skills/` and `.claude/skills/` in every project root (see `src/workspace.rs`),
220 `$SIGIT_CONFIG_DIR/skills/`,
221 and `~/.claude/skills/`. Progressive disclosure: the discovery list (name + description) is
222 baked into the dynamically-built `skill` tool's description, and activating a skill (the model
223 calls `skill` with a name) loads the full `SKILL.md` body. The `skill` tool is appended in the
224 `*_as_specs`/`build_tool_specs` layer (not in `all_tools()`) so its description can be dynamic,
225 and only when at least one skill exists.
226 - **`src/commands.rs`** — user-defined slash commands. Discovers Markdown files (each an
227 optional YAML frontmatter block — `description`, `argument-hint` — followed by a prompt-template
228 body) from `.sigit/commands/` and `.claude/commands/` in every project root, `$SIGIT_CONFIG_DIR/commands/`,
229 and `~/.claude/commands/`. A subdirectory namespaces the command with `:`
230 (`.sigit/commands/git/commit.md` → `/git:commit`). Unlike skills there's no tool-call
231 indirection: invoking one works exactly like the built-in `/init` — `commands::render`
232 substitutes `$ARGUMENTS`/`$1..$9` in the body against whatever followed the command on the
233 input line, and the result is fed to the model as a normal turn through the ordinary tools and
234 permission checks. Resolution happens where each surface (`main.rs`/`chat.rs`) already
235 special-cases `/init`: an unrecognized slash command is tried against `commands::resolve_command`
236 before falling back to "unknown command". A custom command sharing a name with a built-in is
237 unreachable (built-ins match first in `parse_slash`) and is skipped when advertised to ACP
238 clients, with a warning logged.
239 - **`src/subagents.rs`** — configurable subagent types for the `task` tool. Discovers Markdown
240 files (YAML frontmatter `name` + `description`, optional comma-separated `tools:` allow-list,
241 then a Markdown body that becomes the subagent's system prompt) from `.sigit/agents/` and
242 `.claude/agents/` in every project root, `$SIGIT_CONFIG_DIR/agents/`, and `~/.claude/agents/`. Passing a
243 type's `name` as `task`'s `subagent_type` argument swaps in that system prompt and, if `tools:`
244 is set, narrows the offered toolset to its *intersection* with `SUBAGENT_TOOL_NAMES` — the
245 security-relevant narrowing logic lives in `tools.rs` next to that constant, not here; this
246 module only discovers and parses files. `SubagentFactory` (in `tools.rs`) takes the resolved
247 system prompt per call rather than baking one in at registration, so a single registered
248 factory serves both the default research subagent and every configured type.
249 - **`src/frontmatter.rs`** — shared "YAML frontmatter + Markdown body" parsing used by both
250 `src/skills.rs` (`SKILL.md`) and `src/commands.rs` (`.sigit/commands/*.md`).
251 - **`src/mcp.rs`** — [Model Context Protocol](https://modelcontextprotocol.io) *client*. Two
252 transports: **Streamable HTTP** (one JSON-RPC POST endpoint, `url` in `mcp.toml`; replies are
253 `application/json` or SSE) and **stdio** (`command` + optional `args`/`[server.env]` in
254 `mcp.toml`; sigit spawns the server and speaks newline-delimited JSON-RPC over its
255 stdin/stdout, stderr inherited into sigit's log). `url` and `command` are mutually exclusive —
256 both or neither is a config error, logged and skipped. Both transports run the same
257 `initialize`/`tools/list` handshake and forward `tools/call`. Discovery is best-effort at
258 startup (`mcp::init`, called from both branches of `main()`) and cached in a process-global so
259 the synchronous spec builders (`mcp::tool_specs`) and the async dispatch (`mcp::call_tool`) can
260 both read it; `/reload` does *not* re-run it, so config changes need a restart. stdio children
261 live for the process; a dead child fails calls with an in-band error string (no auto-restart).
262 Tools are namespaced `mcp__<server>__<tool>`, appended in the `*_as_specs`/`build_tool_specs`
263 layer and routed in `tools::execute_tool` via `mcp::is_mcp_tool`. Two servers are baked in:
264 the official server (`<cloud>/mcp`, default `https://sigit.si/api/v1/mcp`, always HTTP, authed
265 with the cloud session token) and the smbCloud CLI server (`smb --mcp`, stdio, added only when
266 the `smb` binary is on `PATH`; opt out with `smbcloud = false` in `mcp.toml` or
267 `SIGIT_MCP_SMBCLOUD=off`). A user-defined entry named `sigit` or `smbcloud` overrides the
268 corresponding baked-in one. Extra servers live in `mcp.toml` (global
269 `$SIGIT_CONFIG_DIR/mcp.toml` and project-local `.sigit/mcp.toml`). The stdio path is covered by
270 `tests/mcp_stdio.rs`, driven by the test-only `src/bin/mcp_stdio_stub.rs` helper binary
271 (excluded from the published crate via `exclude` in `Cargo.toml`). The baked-in official
272 server is *also* listed in the public MCP Registry as `si.sigit/sigit` — a **remote**
273 Streamable-HTTP listing owned by the [`getsigit/si`](https://github.com/getsigit/si) repo
274 (`server.json` at its root, published by its `release-mcp-registry.yml`), not this one. Because
275 it's a remote server, the registry's URL-match rule forces a domain namespace (`si.sigit` ↔
276 `sigit.si`) verified by a DNS TXT record, not the GitHub-OIDC scheme `smbcloud-cli` uses for its
277 package listing.
278 Separate from all of the above are the servers an ACP client passes in `mcpServers` on
279 `session/new`, `session/load` and `session/fork`. ACP requires agents to connect to the stdio
280 ones, and they belong to the session that named them, so they cannot live in the startup
281 global: `connect_session_servers` returns a `SessionServers` that `main.rs` keeps on
282 `SessionState` and installs with `set_session_servers` whenever a session becomes live, the
283 same way it swaps the roots. `tool_specs`, `call_tool` and `/mcp` read the startup servers and
284 then the live session's. A client-supplied server whose name is already taken by a startup
285 server is not connected, since both would claim the same `mcp__<server>__` prefix. Streamable
286 HTTP entries are connected too, with the URL and headers the client sent, because
287 `handle_initialize` advertises `mcpCapabilities.http`. SSE is not advertised (the MCP spec
288 deprecated it), so a conforming client never sends one and a stray entry is skipped.
289 - **`src/permissions.rs`** — tool permission policy. Every tool call passes through
290 `decision_for` before executing: read-only tools always run; mutating tools (and all
291 `mcp__*`/unknown tools) are governed by, in order: per-session plan mode (`/plan` — deny all
292 mutating tools with a present-a-plan message), session "always allow" grants, per-tool
293 overrides and the default mode from `[permissions]` in `settings.toml` (`allow`/`ask`/`deny`,
294 default `ask`; `SIGIT_PERMISSIONS` env overrides the default). On `ask`, the ACP path sends
295 `session/request_permission` (allow once / allow for session / deny) and the TUI pauses the
296 inference task on a y/a/n prompt. On the ACP path the decision is taken *before* the call is
297 announced, because it sets the announced status: a call that will ask starts `pending`, the
298 permission request carries that call's own id, and an `in_progress` update follows approval.
299 That update also puts the card's title back, since the permission request overwrites it
300 with the full arguments. The Manual/Auto/Plan choice reaches an ACP client twice: as the
301 `sigit-permission-mode` config option, and as session `modes` with `session/set_mode`, which
302 the spec is retiring but some clients still render instead. Both are built from
303 `PERMISSION_MODES` in `main.rs` and read the same state, so whatever changes the mode has to
304 refresh both (`ConfigOptionUpdate` and `send_current_mode`). Note: ACP turn-affecting handlers run in `cx.spawn`ed tasks
305 so the dispatch loop can route the client's permission answer mid-turn — don't move them back
306 inline, and don't await client requests from inline handlers (deadlock). Two locks order them.
307 A per-session lock (`SiGitAgent::session_lock`) is held for a whole request, so requests on one
308 thread keep their order. `SiGitAgent::workspace_lock` guards what a session installs
309 process-wide (cwd, workspace roots, session MCP servers, the live backend slot, the engine's
310 conversation); lifecycle and config handlers hold it throughout, and `handle_prompt` holds it
311 through a `WorkspaceHold` that it releases while waiting on an HTTP endpoint or a permission
312 answer and retakes (reinstalling its session via `resume_workspace`) before any tool runs. An
313 on-device turn never releases it. Take the session lock first, never the other way round. A turn registers its `PromptCancellation` at
314 the top of `handle_prompt`, before it waits on either lock, and a `PromptRegistration`
315 guard clears it on every return, so a `session/cancel` that arrives while the turn
316 is still queued, switching threads, loading a model or running a slash command ends
317 it as `cancelled`. The checks sit after each of those waits. Tool
318 execution, subagents included, still runs one session at a time.
319 - **`src/instructions.rs`** — project instruction files, the always-on counterpart to skills.
320 Reads `AGENTS.md` (the cross-tool [agents.md](https://agents.md) standard) and `CLAUDE.md`,
321 walking from the session cwd up to the repo root (nearest ancestor with `.git`, never above it),
322 plus a global file under `$SIGIT_CONFIG_DIR`. Files are ordered outermost-first so the deepest
323 (most specific) wins. In a multi-root project that walk is repeated for every root
324 (`load_workspace_instructions`). The combined block is injected via `session_context_message`
325 in `main.rs` — pushed as a system message at every ACP session entry point (new/load/fork +
326 model switch) and appended to the system prompt on the cloud and TUI-startup paths.
327 - **`src/workspace.rs`** — the directories the session treats as project roots. An editor can
328 open several at once (Zed calls it a multi-root project) and ACP carries the extras as
329 `additional_directories` on every session request; the headless CLI takes them as repeatable
330 `--add-dir` flags. A client only sends those extras to an agent that advertises
331 `sessionCapabilities.additionalDirectories` in its `initialize` reply, so that capability in
332 `handle_initialize` is what makes the rest of this reachable — without it Zed keeps the first
333 root, drops the others, and shows "This agent doesn't currently support multi-root workspaces".
334 The process still has one working directory, so the extra roots live in a
335 process-global here and `project_dirs()` returns cwd-first, extras after.
336 One process also serves every thread the editor has open, so that global
337 (with the cwd, the backend conversation, and the background-task owner in
338 `tools.rs`) always belongs to the *live* session: `main.rs` keeps a
339 `SessionState` per session id and `activate_session` parks the live one and
340 installs the requested one before any prompt or config change runs. Don't
341 read another session's roots from the global. Project-local
342 discovery reads it: skills, slash commands, subagent types, and instruction files all scan
343 every root. MCP is deliberately not on that list — `mcp::init` runs once at startup, before
344 any session exists, so a second root's `.sigit/mcp.toml` has nobody to tell. (The servers a
345 client names in `mcpServers` are a different thing and are per session; see `src/mcp.rs`.)
346 - **`src/client_fs.rs`** — file reads and writes through the ACP client. A client that
347 advertises `fs.readTextFile` / `fs.writeTextFile` in `initialize` serves `fs/read_text_file`
348 and `fs/write_text_file` from its buffers, so `read_file` sees unsaved changes and
349 `edit_file` lands in the open buffer instead of underneath it. `tools.rs` has no access to the
350 connection, so this is a seam like the one `mcp::call_tool` gives MCP: `handle_initialize`
351 registers a `ClientFileSystem` (`AcpClientFs` in `main.rs`, holding the connection), and
352 `execute_tool_impl` asks `route_for` before it dispatches `read_file`, `create_file`,
353 `edit_file` or `multi_edit`. Each of those tools is split into a parse step and a pure
354 render/apply step (`ReadFileCall`, `CreateFileCall`, `EditCall`) that the disk path and the
355 client path share, so the model gets the same result text either way. The writing tools also
356 hand back the file before and after (`tools::FileChange`, via `execute_tool_with_change`), which
357 `handle_prompt` sends as ACP `diff` content ahead of the result text. A permission request for
358 one of them carries the same diff, worked out by `preview_file_change` without writing anything
359 and before the workspace is released, since a relative path resolves against the session's cwd. The two capabilities are
360 independent: a client that only reads still gets its edits written to disk. The disk is the
361 fallback throughout: nothing is registered in the TUI or headless modes, a path outside the
362 session's roots is not routed, and a request the client fails or leaves unanswered for 30
363 seconds is retried on disk with a warning in the log. The client is only ever asked from
364 inside a spawned prompt turn, never from `handle_initialize` itself (deadlock, same as
365 permission requests). Existence checks and `create_file`'s parent directories still use the
366 disk. `SIGIT_CLIENT_FS=off` turns the routing off. Covered by `tests/acp_client_fs.rs`.
367 - **`src/client_terminal.rs`** — `run_command` in the ACP client's terminal. A client that
368 advertises `terminal` in `initialize` runs a foreground command itself (`terminal/create`, with
369 the platform shell as `command` and the whole command line as one argument), and
370 `exec_run_command_via_client` embeds the terminal in the tool call as `terminal` content, so the
371 user watches the output live and can stop the command from the editor. The seam is
372 `client_fs`'s: `handle_initialize` registers `AcpClientTerminal`, and `execute_tool_impl` asks
373 `client_terminal_route` before the blocking path. Embedding needs the tool call's id, which is
374 why `execute_tool_with_change` takes one. What `run_command` promises stays put: the 120 s
375 timeout ends in `terminal/kill`, the output is capped, and `CommitWatch` still amends the
376 co-author trailer, checking HEAD on disk before and after. Background commands stay local
377 (`command_output` and `kill_command` read their pipes), and so does a command whose directory
378 is outside the session's roots, since nothing says the editor's machine can see it. A
379 `terminal/create` the client fails means nothing ran, so the command runs locally; a failure
380 after that is reported as the tool's error instead, because running it again could repeat its
381 effects. The finished card keeps the terminal and drops the result text, which still goes out
382 as `raw_output`. `SIGIT_CLIENT_TERMINAL=off` turns the routing off. Covered by
383 `tests/acp_client_terminal.rs`.
384 - **`src/chat.rs`** — the Unix-only ratatui TUI. Loading-spinner phase then chat; uses
385 `tokio::select!` to multiplex terminal events with streaming tokens.
386 - **`src/headless.rs`** — non-interactive `sigit run` execution for scripts, CI, and Factory
387 clients. The legacy `-p` form reaches the same parser. Every new run gets a UUID session id;
388 `--resume <id>` restores that session through `session_store`, and `--output jsonl` emits a
389 structured session/delta/tool/result stream while logs stay on stderr. Headless permission
390 prompts collapse to denial unless the tool was pre-approved with `--allow-tool`.
391 - **`src/session_store.rs`** — durable conversations: one JSON-lines history file per session at
392 `$SIGIT_CONFIG_DIR/sessions/<id>.jsonl`, written atomically, restorable into either backend.
393 Each save also writes a `<id>.meta.json` sidecar naming the session's `cwd` and the extra roots
394 of a multi-root project. That sidecar is what makes a thread *listable*: ACP's `session/list`
395 (advertised as `sessionCapabilities.list`, handled by `handle_list_sessions` in `main.rs` — the
396 editor's "Import Threads" picker) must report an absolute `cwd` per session and may filter on
397 it, so a session without one is skipped there while still reopening by id through
398 `session/load`. Sidecars are written at save time, not at session start, so a thread nobody
399 spoke in leaves nothing behind.
400 - **`src/setup.rs`** — model cache location, local model discovery, selected-model persistence.
401 Must run (`setup_shared_model_cache`) *before* anything touches `ChatEngine`/`hf-hub`, since
402 those read env vars once at init.
403 - **`src/account.rs`** — siGit Code Cloud auth (`/login`, `/logout`, `/whoami`); authenticates
404 against the account API and stores a session token. Performs no console I/O.
405 ACP `logout` (the editor's sign out button, shown only because `handle_initialize` advertises
406 `agentCapabilities.auth.logout`) and `/logout` both go through `SiGitAgent::sign_out` in
407 `main.rs`. The request names no session, so `leave_cloud` moves the parked threads off their
408 cloud tier along with the live one and each of them gets a fresh model picker.
409 - **`src/browser_auth.rs`** — browser sign-in, the path the editor's "Sign in to siGit Code"
410 button takes. sigit is a public OAuth client (client id `sigit-code-cli`, no secret, PKCE
411 S256) against the authorization server at `$SIGIT_API_URL/oauth`. Two ways the code gets
412 back: a loopback listener on `127.0.0.1:0` (the registration lists `http://127.0.0.1/callback`
413 with no port, and RFC 8252 §7.3 matching ignores the port, so one registration covers every
414 run), or the out-of-band URN, where the server renders the code and the user pastes it. The
415 resulting token goes into `credentials` like any other, and is served by `/api/v1/user` rather
416 than the deprecated `/api/v1/me` — OAuth tokens are rejected there. The scopes requested are
417 `user:read code:agent`; `code:agent` is what reaches `chat/completions` and the official MCP
418 server. Surfaces: ACP `authenticate` (loopback only — nowhere to show a code), a bare `/login`
419 in either chat surface, and `sigit login` (which adds the paste fallback, plus `--paste` to
420 force it and `--password` for the old email/password prompt).
421 - **`src/credentials.rs`** — local session-token store (TOML, `0600` on Unix).
422 - **`src/models.rs`** — model-picker types shared across platforms.
423
424 Slash commands (`/help`, `/models`, `/skills`, `/agents`, `/commands`, `/mcp`, `/login`, `/logout`,
425 `/whoami`, `/reload`, `/plan`, `/permissions`, `/init`, `/clear`, `/status`) are advertised via
426 `advertise_commands` in `main.rs` and handled in both the TUI and ACP sessions. `/init` is
427 special: instead of replying directly it substitutes `instructions::INIT_PROMPT` for the user
428 text and runs a normal agent turn that explores the repo and writes (or improves) `AGENTS.md`
429 through the ordinary tools and permission checks. User-defined commands (see `src/commands.rs`)
430 get the same treatment via the `SlashCommand::Unknown` fallback path, so anyone can add their own
431 `/name` commands without touching the built-in command list.
432
433 ## Model cache (macOS)
434
435 On macOS the HF model cache lives in an App Group container shared with the siGit desktop app:
436 `~/Library/Group Containers/group.com.ondeinference.apps/models/`. Other platforms fall back to
437 `~/.cache/huggingface/`. The CLI reuses a model the desktop app already downloaded. First run
438 downloads a GGUF model (~1–2 GB) from Hugging Face.
439
440 ## Logging
441
442 In TTY (interactive) mode, *all* output — `log`, `tracing`, stray `println!` — is redirected to
443 `$TMPDIR/sigit.log` so the ratatui surface stays clean; the TUI holds a separate fd to the real
444 terminal. In ACP mode, stdout is reserved for protocol JSON and logs go to stderr. Control
445 verbosity with `RUST_LOG`.
446
447 ## Relevant env vars
448
449 `OPENAI_BASE_URL` / `OPENAI_API_KEY` (provider override), `SIGIT_API_URL` (account API base,
450 default `https://sigit.si`), `SIGIT_CLOUD_URL`, `SIGIT_CONFIG_DIR` (default `~/.config/sigit`),
451 `SIGIT_MODEL`, `SIGIT_MAX_TOOL_ROUNDS` (1 to 500, default 24; the tool-round cap of a
452 headless run or an ACP prompt turn), `SIGIT_MCP` (`off` disables MCP), `SIGIT_CLIENT_FS` (`off` keeps the file tools on disk even when the
453 ACP client offers `fs/read_text_file` / `fs/write_text_file`), `SIGIT_CLIENT_TERMINAL` (`off` runs
454 `run_command` locally even when the ACP client offers a terminal), `SIGIT_MCP_SMBCLOUD` (`off` drops the baked-in
455 smbCloud CLI server), `SIGIT_MCP_OFFICIAL` (`off` drops the baked-in
456 server), `SIGIT_PERMISSIONS` (`allow`/`ask`/`deny` — overrides the default permission mode for
457 mutating tools; the escape hatch for clients without permission-request support),
458 `HF_HOME` / `HF_HUB_CACHE`, `RUST_LOG`.
459
460 ## Releasing
461
462 Version lives in `Cargo.toml`. Update `CHANGELOG.md` for releases.
463
464 Publishing splits into two groups. **Language registries** each get their own tag-triggered
465 workflow: `release-crates`, `release-npm`, `release-nuget`, `release-pypi`. The `npm/`, `nuget/`,
466 and `pypi/` dirs hold their wrapper-package templates.
467
468 npm and NuGet authenticate with OIDC (Trusted Publishing), so neither needs a stored token. On
469 npm that is configured per package, not per org: all seven `@getsigit/*` names carry a trusted
470 publisher pointing at `release-npm.yml`, and a package added later needs the same setup or its
471 publish step will fail. OIDC also requires npm >= 11.5.1 and Node >= 22.14.0, which is why the
472 workflow upgrades npm and why `.nvmrc` cannot drop below 22.
473
474 **OS package managers** all publish somewhere outside this repo and all need checksums from the
475 GitHub release, so `release-github` builds the binaries, attaches the assets, and then dispatches
476 `release-homebrew`, `release-scoop`, `release-winget`, and `release-aur`. A dispatch failure in one
477 is logged as a warning rather than failing the others, so an unconfigured channel does not block a
478 release. Their inputs live in `packaging/`.
479
480 The Windows binaries link the MSVC C runtime statically (`+crt-static` in `.cargo/config.toml`).
481 winget, Scoop, npm, PyPI and NuGet all ship the bare exe with no installer, so a dynamic build
482 that imports `VCRUNTIME140.dll` fails to load on a machine without the VC++ Redistributable
483 (`0xC0000135`, which is what failed winget's first validation).
484 `packaging/windows/check-static-crt.ps1` runs in CI and in `release-github` and fails the build if
485 a Windows exe imports the runtime again. Don't set a `RUSTFLAGS` env var in those workflows: it
486 replaces the config rustflags instead of adding to them.
487
488 Every release asset now carries a `.sha256` sidecar, not just the macOS Homebrew tarball. Scoop,
489 winget, and the AUR PKGBUILD each need one, and they consume the raw binaries rather than the
490 tarball. `release-github` also builds a `.deb` and `.rpm` per Linux target with nfpm
491 (`packaging/nfpm.yaml`), packaging the already-built binary rather than re-invoking cargo.
492
493 Re-pushing a tag fires every release workflow a second time, so each one is grouped by tag in a
494 `concurrency` block with `cancel-in-progress: false` — the duplicate queues behind the original
495 rather than interrupting a publish that is halfway through uploading. What keeps the queued run
496 from going red is the "is this version already published?" check each publishing workflow does
497 before it uploads. Those checks are load-bearing, not belt-and-braces: v1.5.6 published twice
498 because the crates.io one asked the API with curl's default User-Agent, which crates.io answers
499 with a 403, which read as "not published yet".
500
501 Three of these need credentials or a one-time manual step before they work:
502
503 - Scoop needs a `getsigit/scoop-bucket` repo and a `SCOOP_BUCKET_TOKEN` secret, mirroring the
504 Homebrew tap setup.
505 - winget needs a `WINGET_TOKEN` (PAT with `public_repo` scope) so `wingetcreate` can fork
506 `microsoft/winget-pkgs` and open the manifest PR. It is passed as
507 `WINGET_CREATE_GITHUB_TOKEN` rather than `--token`, which wingetcreate warns can leak the
508 token into logs. `wingetcreate update` only works on a package that already exists in
509 `microsoft/winget-pkgs`, so the workflow checks the `manifests/g/getSigit/siGitCode` path
510 first and falls back to rendering `packaging/winget/*.yaml.in` and running
511 `wingetcreate submit` for a first submission. That fallback runs once, then every later
512 release takes the `update` path. Two non-obvious things in the update path: the `--urls`
513 arguments carry a trailing `|x64` / `|arm64` suffix that tells wingetcreate which installer
514 entry each URL replaces — without it, wingetcreate guesses from the file name, and
515 "sigit-win-amd64.exe" is not a spelling it recognises; and the first-submission render
516 uppercases the SHA256 (`tr '[:lower:]' '[:upper:]'`) to match the community validation
517 pipeline, which writes 64-hex checksums uppercase. The update path also passes
518 `--release-date`, `--release-notes-url`, `--submit`, and `--no-open` explicitly.
519 - The AUR needs `AUR_USERNAME`, `AUR_EMAIL`, and `AUR_SSH_PRIVATE_KEY`. It publishes `sigit-bin`
520 (a prebuilt binary) so Arch users are not compiling the on-device inference stack to install a
521 CLI.
522
523 `[profile.release]` sets `strip = "symbols"` because binary size is a distribution constraint, not
524 just a nicety. See the NuGet note below.
525
526 The NuGet package (`SiGit.Code`, installed with `dotnet tool install --global SiGit.Code`) is the
527 odd one out among the language registries: npm and PyPI publish one artifact per platform, but a
528 .NET tool is a single package, so `nuget/sigit/` bundles all six binaries under
529 `native/<os>-<arch>/` and a small managed shim (`Program.cs`) execs the right one. That shim leaves
530 stdin/stdout/stderr unredirected on purpose, since siGit Code chooses TUI or ACP mode by testing
531 whether stdin is a TTY. It also sets `RollForward=Major`: it targets `net8.0`, and without that a
532 machine carrying only the .NET 10 runtime installs a tool that refuses to start.
533
534 Bundling every target means the package is large, so `release-nuget.yml` fails the pack job if the
535 `.nupkg` crosses nuget.org's 250 MB limit. At v1.5.1 it lands around 160 MB. If a future release
536 trips that check, the fix is not to drop targets but to split into RID-specific tool packages
537 (.NET 10's `DotnetToolRidPackage`), which ship one binary per platform the way npm already does.
538 That also needs a fallback package for pre-.NET-10 SDKs.