main
claude/code-feature-parity-q003hm
claude/elegant-carson-l1menh
claude/sigit-acp-local-chat-cx6380
claude/sigit-cloud-agent-expansion-reox0a
claude/tool-permission-system
claude/zen-feynman-0u78dk
development
feature/agent-tools-multiedit-glob-todos-remember
feature/background-commands
feature/commit-coauthor-attribution
feature/headless-mode
feature/init-command
feature/load-local-model-explicitly
feature/session-persistence-compaction
feature/sigit-code-cloud
feature/subagent-tool
feature/tool-permission-system
feature/tui-repo-tabs
feature/tui-tabs
main
release/v1.3.1
| 1 | --- |
| 2 | name: run-sigit |
| 3 | description: Build, launch, and drive the sigit AI coding agent — run the ACP server, screenshot the interactive TUI, smoke-test the CLI. Use when asked to run sigit, start the agent, screenshot the chat UI, or verify a change to the binary. |
| 4 | --- |
| 5 | |
| 6 | # Run sigit |
| 7 | |
| 8 | `sigit` is a single Rust binary that picks its mode at startup from whether stdin |
| 9 | is a TTY: |
| 10 | |
| 11 | - **ACP mode** (stdin not a TTY): newline-delimited JSON-RPC 2.0 over stdio — the |
| 12 | Agent Client Protocol surface that Zed / VS Code drive. This is the primary |
| 13 | programmatic handle. Drive it with **`.claude/skills/run-sigit/driver.mjs`**. |
| 14 | - **Interactive TUI** (stdin is a TTY): a full-screen ratatui chat, Unix-only. |
| 15 | Drive it under tmux with **`.claude/skills/run-sigit/tui-smoke.sh`**. |
| 16 | - **CLI subcommands**: `sigit login | logout | whoami`, handled before the split. |
| 17 | |
| 18 | Both drivers avoid on-device inference: `initialize`, `session/new`, and slash |
| 19 | commands (`/whoami`, `/help`, `/status`) answer **without** loading a multi-GB |
| 20 | GGUF model, so they work on a clean machine with nothing cached and no network. |
| 21 | |
| 22 | Paths below are relative to the repo root (`<unit>/`). |
| 23 | |
| 24 | ## Prerequisites |
| 25 | |
| 26 | - Rust toolchain (pinned in `rust-toolchain.toml`); `cargo` on PATH. |
| 27 | - Node ≥ 18 for the ACP driver (`driver.mjs`). |
| 28 | - `tmux` for the TUI smoke test only: `brew install tmux` (macOS) / |
| 29 | `apt-get install -y tmux` (Linux). |
| 30 | |
| 31 | ## Build |
| 32 | |
| 33 | ```bash |
| 34 | cargo build # debug binary at target/debug/sigit |
| 35 | ``` |
| 36 | |
| 37 | First build is slow (it compiles `onde` / mistralrs); incremental rebuilds are |
| 38 | sub-second. Use `cargo build --release` for `target/release/sigit` if you want |
| 39 | realistic inference speed — the drivers default to the debug binary. |
| 40 | |
| 41 | ## Run (agent path) |
| 42 | |
| 43 | ### ACP server — `driver.mjs` |
| 44 | |
| 45 | Spawns the binary in ACP mode, runs `initialize` → `session/new` → |
| 46 | `session/prompt /whoami`, prints every frame, exits 0 on success: |
| 47 | |
| 48 | ```bash |
| 49 | node .claude/skills/run-sigit/driver.mjs |
| 50 | # SIGIT_BIN=target/release/sigit node .claude/skills/run-sigit/driver.mjs |
| 51 | ``` |
| 52 | |
| 53 | Expected tail: |
| 54 | |
| 55 | ``` |
| 56 | <-- notify session/update "Signed in to siGit Code Cloud as demo@sigit.si." |
| 57 | "stopReason": "end_turn" |
| 58 | OK — ACP handshake, session, and /whoami round-tripped. |
| 59 | ``` |
| 60 | |
| 61 | The `/whoami` reply arrives as an `agent_message_chunk` notification — the same |
| 62 | streaming surface a real prompt fans out across many chunks. To drive real |
| 63 | streamed inference, send a `session/prompt` with ordinary text instead of a |
| 64 | slash command (needs a cached local model or a signed-in cloud tier). |
| 65 | |
| 66 | ### Interactive TUI — `tui-smoke.sh` |
| 67 | |
| 68 | Launches the TUI under tmux, types `/help`, writes the rendered screen to |
| 69 | `$TMPDIR/sigit-tui.txt` (the "screenshot" for a terminal app), then quits: |
| 70 | |
| 71 | ```bash |
| 72 | .claude/skills/run-sigit/tui-smoke.sh |
| 73 | cat "${TMPDIR:-/tmp}/sigit-tui.txt" # view the captured screen |
| 74 | ``` |
| 75 | |
| 76 | To poke it by hand, the same tmux moves the script automates: |
| 77 | |
| 78 | ```bash |
| 79 | tmux new-session -d -s sigit -x 120 -y 35 |
| 80 | tmux send-keys -t sigit './target/debug/sigit' Enter |
| 81 | sleep 6 |
| 82 | tmux capture-pane -t sigit -p # read the screen |
| 83 | tmux send-keys -t sigit '/help' Enter |
| 84 | tmux send-keys -t sigit C-c # Ctrl+C quits |
| 85 | tmux kill-session -t sigit |
| 86 | ``` |
| 87 | |
| 88 | ### CLI smoke |
| 89 | |
| 90 | ```bash |
| 91 | ./target/debug/sigit whoami # prints the signed-in account, exit 0 |
| 92 | ``` |
| 93 | |
| 94 | ## Run (human path) |
| 95 | |
| 96 | ```bash |
| 97 | cargo run # stdin is your TTY → launches the TUI |
| 98 | ``` |
| 99 | |
| 100 | A full-screen chat opens; type a message or `/help`, Ctrl+C to quit. Useless |
| 101 | headless or with stdin piped — that path falls through to ACP mode instead. |
| 102 | |
| 103 | ## Gotchas |
| 104 | |
| 105 | - **The ACP server never exits on stdin EOF.** `printf '…' | sigit | head` hangs: |
| 106 | the process stays alive holding stdout open, so `head` blocks waiting for bytes |
| 107 | that only stop when you kill it. You must read the response frame and then |
| 108 | `kill` the child — that's the whole reason `driver.mjs` exists instead of a |
| 109 | one-line pipe. |
| 110 | - **Piping stdin forces ACP mode.** Any non-TTY stdin (a pipe, `</dev/null`) |
| 111 | routes to the JSON-RPC server, not the TUI. The TUI needs a real PTY, hence |
| 112 | tmux. |
| 113 | - **Handshake is intentionally model-free.** `initialize` / `session/new` defer |
| 114 | GGUF loading to the first real prompt, so they're fast and need no network. A |
| 115 | text `session/prompt` to an on-device model triggers a ~1–2 GB download on |
| 116 | first use. |
| 117 | - **The default model depends on sign-in state.** On a signed-in machine the |
| 118 | picker shows a cloud tier (e.g. `onde-cloud (onde-fast)`); logged out it |
| 119 | defaults to an on-device model. `sigit whoami` shows which. |
| 120 | - **Logs go to different places per mode.** ACP mode → stderr (the driver prefixes |
| 121 | them `[sigit]`). TUI mode redirects all stdout/stderr to `$TMPDIR/sigit.log` so |
| 122 | the ratatui surface stays clean — tail that file to debug the TUI. |
| 123 | - **macOS model cache is shared with the desktop app**, under |
| 124 | `~/Library/Group Containers/group.com.ondeinference.apps/models/`; other |
| 125 | platforms use `~/.cache/huggingface/`. |
| 126 | |
| 127 | ## Troubleshooting |
| 128 | |
| 129 | - `binary not found: target/debug/sigit` → run `cargo build` first. |
| 130 | - Driver hangs / times out on `initialize` → you're likely running a stale binary |
| 131 | or one that crashed at startup; check the `[sigit]` stderr lines it echoes. |
| 132 | - `tmux not installed` from `tui-smoke.sh` → `brew install tmux`. |
| 133 | - TUI capture is blank → increase the `sleep` before `capture-pane`; the banner |
| 134 | and (lazy) model selection take a few seconds on a cold start. |