This repository is a Rust workspace with a root application crate and small
domain crates. The extracted crates keep frequently edited functionality from
forcing unrelated heavyweight dependencies to rebuild. The product is the
orchestrator app in apps/desktop; the TUI in rustcode/tui is a second front
end over the same engine.
rustcode/
├── core/ Domain libraries. No terminal UI, no frontend assumptions.
│ ├── rustcode-core/ stable shared types and path helpers
│ ├── rustcode-session/ session persistence primitives
│ ├── rustcode-tool-protocol/ tool-call protocol envelopes
│ ├── rustcode-tools/ filesystem tool implementations
│ ├── rustcode-command/ cross-platform command execution
│ ├── rustcode-lifecycle/ turn lifecycle and stop-state types
│ ├── rustcode-tasks/ background task state and event delivery
│ └── rustcode-loop-detect/ semantic loop and progress guards
├── client/ `rustcode-client`, the machine client: saved machines, pairing
│ and the WebSocket to another machine's gateway.
├── engine/ Sources of the root `rustcode` crate (library only): agent
│ loop (the built-in harness), tools, config, session state, ACP,
│ daemon, controller.
└── tui/ `rustcode-tui`, the terminal frontend. Owns the `rustcode`
binary (TUI + headless/ACP/daemon CLI modes); depends on the
root library, never the reverse.
The desktop app in apps/desktop (Tauri + React, see desktop)
runs the engine over ACP. The SwiftUI macOS app it replaced was removed;
macOS app architecture maps it for history.
The root Cargo.toml is both the workspace manifest and the rustcode
package manifest; the engine lives in rustcode/engine/src and is declared
with [lib] path. There are no Cargo features left: the terminal stack
(ratatui, crossterm, syntect, pulldown-cmark) lives only in rustcode/tui.
Nothing under rustcode/core or rustcode/engine may reference it;
cargo tree -p rustcode -i ratatui must match nothing. See docs/frontends.md for the frontend contract and
docs/mobile.md for the remote-only mobile decision.
| Crate | Responsibility |
|---|---|
rustcode-core |
Stable shared domain types and executable-path helpers |
rustcode-session |
Session persistence primitives |
rustcode-tool-protocol |
Tool-call protocol parsing and envelopes |
rustcode-tools |
Filesystem-oriented tool implementations |
rustcode-command |
Cross-platform command execution and bounded output |
rustcode-lifecycle |
Turn lifecycle and stop-state types |
rustcode-tasks |
Session-aware background task state and event delivery |
rustcode-loop-detect |
Semantic loop, failure, progress, and reasoning guards |
rustcode-client |
The machine client: saved machines and routes, ask-to-connect pairing, the device-token store, the WebSocket transport and ACP over another machine's gateway. Used by rustcode machines and, later, the desktop app's Rust shell |
The root rustcode crate owns integration concerns: model/network turns,
ACP, configuration, the terminal UI state, and adapters
between the smaller crates.
model tool call
-> tool protocol envelope
-> network tool execution
-> root tool dispatcher
-> rustcode-command (foreground)
or rustcode-tasks + rustcode-command (background)
-> session-scoped event consumer
-> history + UI/headless/ACP continuation
The task manager is process-scoped, but all listing, status, cancellation, and event routing enforce session ownership. Consumers subscribe before work can spawn so fast commands cannot complete before an observer exists.
Interactive, headless, and ACP consumers have separate adapters:
- The interactive runtime preserves inactive-session subscriptions until their terminal events have been drained.
- Headless execution tracks only tasks created by its current turn.
- ACP uses a server-owned router with bounded per-session delivery, durable persistence, provider call-ID correlation, and ordered terminal updates.
- OS process termination is performed outside the task-state mutex.
- A
Terminatingstate retains a racing process completion until cancellation commits its outcome. - Terminal transitions are idempotent and publish once.
- Terminal IDs are retained in a bounded ledger for race classification.
- Event publication is synchronized with quiescence checks so a consumer cannot prune a subscription while its terminal event is still in flight.
- Slow task subscribers are disconnected rather than allowed to block workers.
The viewport projects committed history and the current live assistant/tool cell into one sequence of wrapped rows. The live cell is measured before the combined viewport is sliced, so its older rows remain reachable while output grows. Only the history suffix needed for the viewport and scroll offset is rendered; committed blocks and the live assistant cell reuse their presentation caches.
A zero scroll offset follows the newest row. Manual scrolling records the committed tail and live row counts at the current width; subsequent frames adjust the offset by rows added below the reader, including the handoff from live output to completed or cancelled history. Height changes preserve the top reading row. Width changes rewrap the semantic cells and establish a new reading anchor. The existing return-to-bottom control resumes following and clears unseen activity. Mouse selections continue to project their immutable snapshot, including live text, so streaming cannot change selected or copied rows.
Desktop shell and shared client changes run blocking Linux/Windows cargo check --all-targets jobs in Desktop CI, alongside the macOS shell checks; UI-only changes skip them.
Changes under rustcode/ and CI helper scripts trigger the required Linux test
and lint jobs, plus advisory macOS/Windows portability checks. The required
test and lint jobs run in parallel so merges do not wait for their combined
compile time. Release artifacts are built for:
- Linux x86_64
- macOS Apple Silicon (ARM64)
- Windows x86_64
Intel macOS is intentionally not part of the release matrix.
The Build workflow runs for version tags and manual dispatches only. A push
to main does not rebuild all release targets; the tag build is the single
source of published artifacts. Use manual dispatch on a branch when a release
binary needs validation without creating a release.
The release script performs a lightweight local preflight, opens a release PR,
waits only for required PR checks, and then tags the merged commit. Use
--full-verify when a complete local test run is desired before opening the
release PR.
Use scripts/bench-build-boundaries.md
to measure clean, warm, and focused-edit Cargo rebuild costs without cleaning a
shared target directory.
~/.config/rustcode/index.sqlite (engine/src/thread_index.rs) indexes the
thread folders: a threads table (title,
folder, message count, folder mtime) and an FTS5 trigram index over user and
assistant messages (each capped at 6,000 characters). The folders stay the
source of truth: the engine refreshes the index from them at start, in the
background, and before each search, reading only folders whose mtime moved;
a missing or unreadable index is deleted and rebuilt. Migrations are
numbered and recorded with their names, and a name mismatch refuses to open
instead of skipping a step. _rustcode/threads/search { query, limit? }
answers { results: [{ session_id, title, snippet, updated_at }] }.
~/.config/rustcode/data.sqlite (engine/src/data_store.rs) keeps the
metadata the folders cannot answer cheaply: threads, turns (tokens, cost,
outcome, tool-call count) and tool calls, plus a daily_usage view by day,
harness and model. It is not a cache like the thread index: per-turn token
deltas of an external harness cannot be rebuilt, so the file is kept.
Metadata only — no message text, tool arguments or output. The engine writes
it beside track_usage for its own turns and when an external harness's
prompt returns (reading Claude Code's and Pi's own session logs for the token
counts their usage_update omits), backfills existing folders once in the
background, and exposes reads through rustcode usage and
rustcode data query. See data store.