Silo — project guide for coding agents

Silo keeps all your projects alive at once — for developers juggling coding agents (Tauri + React + TypeScript). Open many workspaces and switch instantly; each keeps its terminals, agents, panels, and layout intact in the background. 100% open source, free forever. Extensible: modeled on VS Code / Obsidian with a small stable core, a public extension SDK, and first-party features built as extensions — so the bar for boundaries, documentation, and a clean public surface is high.

Product positioning for humans lives in README.md / apps/docs/index.md / context7.json. Prefer those over inventing a tagline. This file is agent orientation (architecture, boundaries, commands), not marketing copy.

Orientation docs (read when relevant):

• docs/architecture.md — the structural map: packages and their dependency edges, layering inside the host, the Rust/webview process split, persistence destinations, and the two published surfaces. Facts-only and drift-checked; start here when you don't yet know where something lives. The rules for staying inside those boundaries are below, under "Architecture boundaries".
• docs/architecture-review-workflow.md — how a change gets an architectural review end to end: the silo-architecture-review skill, spot-checking its findings, and the author → reviewer → fixer session split.
• docs/decisions/ — ADRs: the architecture decisions of record (the durable "why").
• docs/proposals/ — RFCs: forward-looking designs not yet decided.
• docs/change-planning-convention.md — how a substantial change is planned: proposal → (temporary) planning package → implementation → verification → collapse back to one durable proposal. See "Planning a substantial change" below.
• docs/domain-language.md — the domain glossary: ubiquitous language for the product, including UI component naming (Panels & Docking, Navigator, …). Kept current via the workflow in .agents/skills/silo-domain-modeling/SKILL.md.
• docs/silo-extensions-repo.md — the external silo-code/silo-extensions repo (cloned at ../silo-extensions): how its third-party extensions relate to this repo — published-SDK lag, npm (not pnpm) build commands, runtime trust / silo.permissions, and how to install a branch without merging. They publish into the registry; discovery is Browse / extensions.getsilo.dev, not cloning that repo.
• docs/extensions-registry-repo.md — the external silo-code/extensions-registry repo (cloned at ../extensions-registry): git-backed catalog behind extensions.getsilo.dev (humans) and registry.getsilo.dev (app/CLI index). How it relates to in-app Browse / install / update in this monorepo.
• apps/docs/guide/extension-checklist.md — pre-flight checklist for any extension (bundled or third-party): boundaries, permissions, styling, lifecycle, packaging, stability.

Explaining your work

Answer at the level of the system, not the file. The reader of your summaries and PR prose thinks in Silo's architecture — the Host, the public surface, ctx, trust tiers, the boundary — and is usually deciding whether a change is architecturally right, not whether a particular line is correct.

• Lead with the contract. What moved on the host ↔ extension boundary: did this widen the public surface, add a capability to ctx, lean on the privileged surface, or stay entirely inside one extension? If nothing moved, say that — it's the most useful sentence in the summary.
• Use the glossary's nouns. docs/domain-language.md exists so a change can be described in shared terms. Reach for the term, not a paraphrase, and if the right term doesn't exist yet, that's a signal to add it (see "Domain language" above) rather than to invent a one-off synonym.
• Paths are supporting evidence, not the explanation. Name a file when the reader needs to find something or when the location is the point (which package a capability landed in, for instance). A summary that is mostly file and symbol names has described the diff without explaining the change.
• Be brief and lead with the answer. State the outcome first, then the reasoning that changes what someone would do about it. Detail is available on request; volume is not a substitute for altitude.

This governs prose — summaries, PR descriptions, review notes, answers to questions. It is not a reason to skip the precision a code comment or an ADR needs.

Engineering principles

• Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection in implementation code. This doesn't apply to the public SDK surface (ctx, @silo-code/sdk) — that's designed ahead of full usage on purpose (see the roadmap's planned → stable flow above); the bar there is deliberate API design, not premature abstraction.
• Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.
• Keep components modular and concerns clearly separated.
• Prefer established, well-maintained libraries over reimplementing common functionality, and lean on dependencies already in the project before adding new ones or writing your own. Don't assume a library lacks a capability without checking its docs and types.
• Make architectural decisions for the long term. Don't accept a stopgap that only works for now and is meant to be replaced later.

Self-documentation — keep docs in sync AS YOU BUILD

The API reference is generated from the source, so touching the public extension surface (the @silo-code/sdk barrel packages/sdk/src/index.ts and everything it re-exports) means doing the docs in the same change — never as a follow-up. When you add or change a public symbol — a new ctx method, type, or field — run the full workflow (TSDoc, @public/@internal + @category tags, barrel re-export, the hand-authored ctx member page, pnpm docs:api, flipping the roadmap badge) and the Context7 indexing contract for context7.json — documented in .agents/skills/silo-docs-sync/SKILL.md.

Docs-driven development: the public Roadmap (apps/docs/roadmap.md) is the source of truth for what's real; design decisions live as ADRs (docs/decisions/) and proposals (docs/proposals/). Design a new primitive by adding it to the roadmap as planned (with its sketched surface) first, then implement it and flip it to stable. Expanding ExtensionContext (ctx) is the main ongoing work — and the moment to run through that workflow.

Planning a substantial change

A change with real product/architectural/API/persistence impact, cross-cutting reach, significant complexity, or ambiguity needing explicit decisions gets a proposal. Small, low-risk changes (typo/CSS/dep-bump/localized fix) don't — implement those directly. Full workflow: change-planning convention.

• Proposal — one docs/proposals/NNNN-name.md (template): problem, motivation, proposed change, rough scope.
• Planning package — once accepted and implementation is starting, expand that file into docs/proposals/NNNN-name/ with proposal.md, requirements.md, design.md, tasks.md (skeletons). These three planning files are temporary. Implement against them, keep tasks.md current, follow existing ADRs, fix the design when the code contradicts it, ship tests in the same change.
• Verify against every requirement and acceptance criterion (pnpm test / tsc --noEmit / pnpm lint), then collapse: delete requirements.md / design.md / tasks.md and rewrite the directory back to one curated docs/proposals/NNNN-name.md. Curate the durable intent and outcome — don't concatenate. status: implemented once every phase the proposal commits to has shipped; for a change planned in multiple phases, collapse keeps status: accepted and re-expands for the next phase — see "Multi-phase changes" in the convention doc.

The durable record is the collapsed proposal plus any ADR (docs/decisions/) for a lasting architectural decision; the code and tests are the truth of how it works now. The implementation may live in another repo (e.g. an extension in silo-code/silo-extensions) — the proposal stays here and names it.

Domain language — keep the glossary in sync AS YOU BUILD

When you introduce or resolve domain vocabulary — a new concept worth naming, a naming collision, a term that needs sharpening — update docs/domain-language.md in the same change, not as a follow-up. Prefer terms already there over inventing synonyms. When the change is also a candidate for a durable decision record, write the ADR (docs/decisions/) or RFC (docs/proposals/) alongside it — see docs/decisions/README.md / docs/proposals/README.md for which one and the format. Do this actively — challenge fuzzy terms, work through edge-case scenarios, and write the result down the moment it crystallizes, not after the fact — per the workflow in .agents/skills/silo-domain-modeling/SKILL.md.

Architecture boundaries — enforced, don't regress

The repo is a pnpm workspace; the boundary is now expressed by the package graph. This section is the mechanics; the vocabulary for talking about it — Host, public surface, privileged surface, trust tier, boundary — is defined under "Platform Architecture" in docs/domain-language.md. The relevant packages:

• @silo-code/sdk (packages/sdk) — the public, types-first leaf. The only surface silo.* and third-party extensions may import.
• @silo-code/extension-host (packages/extension-host) — the workbench host runtime (state, services, layout, docked, panels, components, the registry + loader that provide ctx). Owns the privileged @silo-code/extension-host/internal subpath, importable by core.* only.
• @silo-code/extensions-core (core.*) / @silo-code/extensions-silo (silo.*) — the bundled first-party extensions.

Extensions must touch the app only through ctx and @silo-code/sdk types — never the host's state/services/layout/panels/docked/components. This is enforced first by package visibility: a package can only resolve what it declares as a dependency. @silo-code/extensions-silo depends on @silo-code/sdk alone, so a silo.* extension physically cannot import the privileged surface (or another extension package); @silo-code/extensions-core depends on the host, so it can. Lint (the repo-root eslint.config.js + stylelint.config.js, run via pnpm lint and the pre-commit hook) covers what the graph can't express: the platform ban (no raw @tauri-apps/* or node:* in extensions — route through ctx), host-internal leaf layering (state/services don't import out), and the design-token-only CSS rule.

• Do not add new boundary violations. If an extension needs a capability the SDK lacks, that's a signal to add it to ctx (and document it), not to reach into internals.
• The old ESLint/stylelint ratchet baselines retired with the monorepo — the one seam they baselined (silo git-explorer ↔ git) is now a legitimate intra-package import. There is no suppressions file to prune; new violations simply fail.

The design-system kit (RFC 0016 / ADR 0026 — Button, List, ModalActions, …) has one source: the public @silo-code/sdk. There is no internal fork — the host and bundled extensions consume the same components at HEAD via workspace:*, so first-party Silo UI and third-party extension UI build from identical markup. When building Silo, reach for the kit, don't re-hand-roll a modal input/list/badge. The host may import kit components from @silo-code/sdk just as it imports SDK types (host → SDK is the normal leaf direction; nothing lints against it). The chrome line: the kit covers the content of modals, settings pages, and property tabs; host chrome — the <Modal> shell (ADR 0018), the Settings rail, the status-bar container, panels, the title bar — stays bespoke and host-owned, styled via component tokens. See ADR 0026 for the full rationale and the version asymmetry (internal rides HEAD, third parties ride the last published SDK).

The CSS surface (the theming contract — ADR 0017 + the public token reference apps/docs/api/theming.md): all host design tokens are --silo-*, and an extension's CSS may consume only the design tokens (--silo-color-*, --silo-font*, --silo-radius-*, --silo-button-*) — never a component token (--silo-content-*, --silo-statusbar-*, …) or an internal token (--silo-internal-*). Enforced by the stylelint rule silo/extension-design-tokens-only (folded into pnpm lint, run over each extension package's CSS). Don't hard-code colors/fonts/px sizes in extension CSS — that breaks theming and uiFontSize scaling.

Don't hand-roll focus styles. There is one shared focus ring — the global :focus-visible rule in packages/extension-host/src/layout/theme.css gives every interactive element (button, input, [role="button"], …) the accent outline. Adding a per-element focus style (e.g. recoloring the border on :focus) stacks a second ring on top of it, producing a double outline. Rely on the shared ring; if you must suppress the native one on a base element use outline: none (the global rule has higher specificity and still wins on focus).

Every tooltip uses the SDK Tooltip, never the native title attribute. Tooltip (packages/sdk/src/Tooltip.tsx) is the one tooltip implementation — consistent 600ms delay, styling, and positioning app-wide, both in the host chrome and every extension. A native title attribute renders with the browser's own (unstyled, immediate-on-hover, per-OS) tooltip instead, which looks inconsistent next to every other tooltip in the app. This applies everywhere a hover hint is needed, not just on already-interactive elements — wrap the target in <Tooltip content="...">...</Tooltip>.

Commands

All run from the repo root (pnpm workspace).

Conventions

• Match the surrounding code's style; the ESLint config enforces boundaries, not formatting.
• Bundled extensions live in packages/extensions-core/src/<name>/ (core.*) or packages/extensions-silo/src/<name>/ (silo.*), are re-exported from that package's barrel (src/index.ts), and are wired in by the app's composition root (apps/desktop/src/builtins.ts), which hands the ordered list to the host's activateExtensions. Model new ones on image-viewer (editor, silo.*) or about (settings page, core.*) — both touch the app only through ctx. Run through the extension checklist before calling a new one done.
• No legacy/internal brand names in source — the product is Silo.
• Docs under docs/ use lowercase kebab-case filenames (automation.md, domain-language.md), not ALLCAPS. The only exception is the conventional README.md.
• All host-side logging goes to the Output panel, never console.*/devtools. Use createHostChannel (packages/extension-host/src/extension-host/output-store.ts) to log from host code. Before adding a new channel, check whether an existing one is a close fit (e.g. silo:application/"Application" for core.* extension activity, silo:extension-host/"Extension Host" for host lifecycle) — only create a dedicated channel (e.g. silo:agents/"Agents") when the thing being logged is genuinely a new subsystem with its own diagnostic surface.
• Terminal attach / restart post-mortems: durable trail is ~/Library/Application Support/com.silo.desktop.dev/logs/terminal.log (prod: com.silo.desktop). Rust writes app_boot, host_*, attach*; the UI mirrors attach decisions as ui_* via logTerminalAttachTrace (packages/extension-host/src/extension-host/terminal-attach-trace.ts) into both that file and Output → Terminals (silo:terminals). After a weird restart, grep app_boot|ui_|host_attach|host_incompatible|attach_gone — see RFC 0026 verification. Do not diagnose reattach from Output alone (it clears with the webview).
• Commit messages and PR titles are Conventional Commits: type(scope): summary — e.g. feat(git-explorer): add "View Commits" drill-down, fix(file-explorer): scope "View Commits" to the branch. Check git log for the type/scope vocabulary already in use before inventing a new scope. This isn't just a style nit: GitHub squash-merges every PR using its title as the resulting commit message on main, so an untitled/prose PR title (e.g. "Fix some file explorer bugs") becomes the permanent, non-conventional entry in git log — get the title right before opening the PR, not after.

Testing — write unit tests for all new functionality

Every change that adds or changes behavior ships with unit tests in the same change. Tests are part of the work, not a follow-up — the same way docs are (see "Self-documentation" above). Don't mark a task done until pnpm test is green with coverage for what you added. For the repo's conventions — co-located Vitest, the pure-logic (no @testing-library/react) style and how to extract testable helpers, driving host state via the store proxy, and the contract-and-edges coverage bar — see .agents/skills/silo-testing/SKILL.md.

Reference docs

Issue tracker

Issues live as GitHub issues in silo-code/silo, via the gh CLI. See docs/issue-tracker.md.

Triage labels

Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See docs/triage-labels.md.

Adding a coding agent

How a coding-agent CLI (Claude Code, Codex, Cursor, Copilot, Grok, …) becomes a known agent in Silo: the recon to do against the running binary, the AGENT_CATALOG entry, activity detectors, resume strategies, and every surface that names agents in prose. See docs/adding-a-coding-agent.md.

ACP coverage

Which Agent Client Protocol features Silo's hand-rolled client uses, which are available but unused, and the ranked shortlist of what to add next. Silo has no @agentclientprotocol/sdk dependency, so no version bump signals that the protocol moved — this doc is the record instead. Regenerate it with the silo-acp-watch skill (the git diff is the delta); the Top 5 and Analysis sections are hand-written and survive regeneration. See docs/acp-coverage.md.

Modal & extension UI design

Decision table for building modal content, settings pages, or workspace property tabs with the Design System kit — which surface, which component, and the forbidden list. See docs/modal-design.md.

Side panel & sheet UI design

Decision table for side panels and dock-anchored sheets — typography, toolbars, and drill-in ("Back") paging. Overlaps the modal kit but has its own chrome rules. See docs/side-panel-design.md.