claude/sigit-acp-local-chat-cx6380
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 | # CLAUDE.md |
| 2 | |
| 3 | This file provides guidance to Claude Code (claude.ai/code) 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 | ## Build / test / lint |
| 21 | |
| 22 | ```sh |
| 23 | cargo build # debug build |
| 24 | cargo build --release # release binary at target/release/sigit |
| 25 | cargo run # launches interactive TUI (stdin is a TTY) |
| 26 | cargo test # CI runs: cargo test --locked --target <target> |
| 27 | cargo clippy --tests -- -D warnings # CI gate: clippy is -D warnings on all 4 targets |
| 28 | cargo fmt -- --check # CI gate (edition 2024) |
| 29 | ``` |
| 30 | |
| 31 | CI (`.github/workflows/ci.yml`) runs fmt + clippy + test across four targets: |
| 32 | `aarch64-apple-darwin`, `x86_64-apple-darwin`, `x86_64-unknown-linux-gnu`, |
| 33 | `x86_64-pc-windows-msvc`. Clippy is `-D warnings`, so warnings fail the build. |
| 34 | |
| 35 | Run a single test: `cargo test <test_name>`. |
| 36 | |
| 37 | ## Critical platform constraint: `#[cfg(unix)]` dead code |
| 38 | |
| 39 | The interactive client, the `InferenceBackend` seam (`backend.rs`), and provider resolution |
| 40 | (`provider.rs`) are wired up **only** through `#[cfg(unix)]` code paths. On Windows the binary |
| 41 | runs ACP-only and drives `onde` directly, so much of `backend.rs` and `provider.rs` is |
| 42 | legitimately unused there and the dead-code lint is suppressed *on non-Unix targets only*. |
| 43 | |
| 44 | Consequence: code can pass clippy on macOS/Linux but fail on the Windows target (or vice versa). |
| 45 | When touching `backend.rs`, `provider.rs`, or the interactive path, keep the `cfg` gates intact — |
| 46 | don't "fix" an unused-warning by deleting code that's live on Unix. |
| 47 | |
| 48 | ## Architecture |
| 49 | |
| 50 | The agent loop is backend-agnostic. The flow: a turn (messages + tool specs) goes to an |
| 51 | `InferenceBackend`, which returns assistant text and/or tool calls; the loop executes tools and |
| 52 | feeds results back. Neither the loop nor ACP/TUI surfaces depend on a concrete backend. |
| 53 | |
| 54 | - **`src/main.rs`** — entry point, mode dispatch, the full ACP `Agent` impl (session lifecycle: |
| 55 | new/load/fork/prompt/cancel, config options, slash-command advertisement), and the `SYSTEM_PROMPT` |
| 56 | (note: it bakes in smbCloud-specific context the agent should use when the repo is clearly |
| 57 | smbCloud, and stay general otherwise). |
| 58 | - **`src/backend.rs`** — the `InferenceBackend` trait and neutral types (`ToolSpec`, `ToolCall`, |
| 59 | `ToolResult`, `TurnResult`). Two impls: `LocalBackend` (on-device via `onde::ChatEngine`) and |
| 60 | `OpenAiBackend` (any OpenAI-compatible HTTP endpoint). |
| 61 | - **`src/provider.rs`** — decides *which* backend serves inference. Resolution order, first match |
| 62 | wins: (1) override via `OPENAI_BASE_URL`+`OPENAI_API_KEY` or active profile in |
| 63 | `~/.config/sigit/providers.toml`; (2) siGit Code Cloud when logged in; (3) on-device. |
| 64 | - **`src/tools.rs`** — agent tool schemas + execution: `read_file`, `create_directory`, |
| 65 | `list_directory`, `search_files`, `read_website`, `create_file`, `edit_file`, `delete_file`, |
| 66 | `run_command`. Add a tool in both the spec list and the execute `match`. |
| 67 | - **`src/skills.rs`** — [Agent Skills](https://agentskills.io) support. Discovers skill |
| 68 | folders (each with a `SKILL.md`: YAML frontmatter `name` + `description`, then Markdown |
| 69 | instructions) from `.sigit/skills/` and `.claude/skills/` in the cwd, `$SIGIT_CONFIG_DIR/skills/`, |
| 70 | and `~/.claude/skills/`. Progressive disclosure: the discovery list (name + description) is |
| 71 | baked into the dynamically-built `skill` tool's description, and activating a skill (the model |
| 72 | calls `skill` with a name) loads the full `SKILL.md` body. The `skill` tool is appended in the |
| 73 | `*_as_specs`/`build_tool_specs` layer (not in `all_tools()`) so its description can be dynamic, |
| 74 | and only when at least one skill exists. |
| 75 | - **`src/instructions.rs`** — project instruction files, the always-on counterpart to skills. |
| 76 | Reads `AGENTS.md` (the cross-tool [agents.md](https://agents.md) standard) and `CLAUDE.md`, |
| 77 | walking from the session cwd up to the repo root (nearest ancestor with `.git`, never above it), |
| 78 | plus a global file under `$SIGIT_CONFIG_DIR`. Files are ordered outermost-first so the deepest |
| 79 | (most specific) wins. The combined block is injected via `session_context_message` in `main.rs` |
| 80 | — pushed as a system message at every ACP session entry point (new/load/fork + model switch) |
| 81 | and appended to the system prompt on the cloud and TUI-startup paths. |
| 82 | - **`src/chat.rs`** — the Unix-only ratatui TUI. Loading-spinner phase then chat; uses |
| 83 | `tokio::select!` to multiplex terminal events with streaming tokens. |
| 84 | - **`src/setup.rs`** — model cache location, local model discovery, selected-model persistence. |
| 85 | Must run (`setup_shared_model_cache`) *before* anything touches `ChatEngine`/`hf-hub`, since |
| 86 | those read env vars once at init. |
| 87 | - **`src/account.rs`** — siGit Code Cloud auth (`/login`, `/logout`, `/whoami`); authenticates |
| 88 | against the account API and stores a session token. Performs no console I/O. |
| 89 | - **`src/credentials.rs`** — local session-token store (TOML, `0600` on Unix). |
| 90 | - **`src/models.rs`** — model-picker types shared across platforms. |
| 91 | |
| 92 | Slash commands (`/help`, `/models`, `/skills`, `/login`, `/logout`, `/whoami`, `/reload`, |
| 93 | `/clear`, `/status`) are advertised via `advertise_commands` in `main.rs` and handled in both the |
| 94 | TUI and ACP sessions. |
| 95 | |
| 96 | ## Model cache (macOS) |
| 97 | |
| 98 | On macOS the HF model cache lives in an App Group container shared with the siGit desktop app: |
| 99 | `~/Library/Group Containers/group.com.ondeinference.apps/models/`. Other platforms fall back to |
| 100 | `~/.cache/huggingface/`. The CLI reuses a model the desktop app already downloaded. First run |
| 101 | downloads a GGUF model (~1–2 GB) from Hugging Face. |
| 102 | |
| 103 | ## Logging |
| 104 | |
| 105 | In TTY (interactive) mode, *all* output — `log`, `tracing`, stray `println!` — is redirected to |
| 106 | `$TMPDIR/sigit.log` so the ratatui surface stays clean; the TUI holds a separate fd to the real |
| 107 | terminal. In ACP mode, stdout is reserved for protocol JSON and logs go to stderr. Control |
| 108 | verbosity with `RUST_LOG`. |
| 109 | |
| 110 | ## Relevant env vars |
| 111 | |
| 112 | `OPENAI_BASE_URL` / `OPENAI_API_KEY` (provider override), `SIGIT_API_URL` (account API base, |
| 113 | default `https://sigit.si`), `SIGIT_CLOUD_URL`, `SIGIT_CONFIG_DIR` (default `~/.config/sigit`), |
| 114 | `SIGIT_MODEL`, `HF_HOME` / `HF_HUB_CACHE`, `RUST_LOG`, `SIGIT_DISABLE_APP_GROUP` (macOS: skip the |
| 115 | shared Onde App Group model cache so the cross-app data privacy prompt never fires; falls back to |
| 116 | `~/.cache/huggingface`). |
| 117 | |
| 118 | ## Session persistence (ACP) |
| 119 | |
| 120 | ACP chat transcripts persist per `SessionId` under `$SIGIT_CONFIG_DIR/sessions/<id>.json` (see |
| 121 | `src/sessions.rs`). Each completed user/assistant turn is appended in `handle_prompt`; on |
| 122 | `session/load` (and `session/fork`) the transcript is replayed to the editor and pushed back into |
| 123 | the active backend via `InferenceBackend::restore_history`, so reopening a thread in Zed resumes it |
| 124 | instead of starting blank. `/clear` wipes both the engine history and the stored file. |
| 125 | |
| 126 | ## Releasing |
| 127 | |
| 128 | Version lives in `Cargo.toml`. The binary is published to five registries via separate workflows |
| 129 | (`release-crates`, `release-github`, `release-homebrew`, `release-npm`, `release-pypi`); the |
| 130 | `npm/` and `pypi/` dirs hold the wrapper-package templates. Update `CHANGELOG.md` for releases. |