@setoelkahfi / sigit
Code Commits Pulls 2 CI/CD
claude/code-feature-parity-q003hm
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
md 120 lines 7.1 KB
Rendered Raw
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`.
115
116 ## Releasing
117
118 Version lives in `Cargo.toml`. The binary is published to five registries via separate workflows
119 (`release-crates`, `release-github`, `release-homebrew`, `release-npm`, `release-pypi`); the
120 `npm/` and `pypi/` dirs hold the wrapper-package templates. Update `CHANGELOG.md` for releases.