hilash/cabinet

1. Overall shape

Cabinet is a local-first AI workspace made of three main runtime surfaces: a Next.js web app, a long-running local daemon, and a CLI/bootstrap layer. The web app is the primary UI, the daemon handles long-running work, and the CLI installs/updates/runs the app in a user’s machine-local Cabinet directory.

2. Core data model: files first

The knowledge base is stored as markdown and other files on disk, not in a remote SaaS database. Most product features revolve around reading, writing, moving, versioning, and rendering those files. Git is used as the history layer, so edits are effectively captured as commits and diffs rather than opaque app records.

3. Web app boundary

src/app is a large Next.js app router surface. It exposes the UI, plus a broad set of API routes under src/app/api/* that act as the app’s backend boundary. The UI is mostly React components in src/components, with Zustand stores in src/stores for client state and interaction flows.

4. Server-side application services

src/lib contains the actual domain logic behind most routes: storage, git history, file I/O, search, onboarding, telemetry, auth, agents, integrations, and system operations. The API routes are thin orchestration layers that call into these libraries, which keeps the architecture centered on reusable local services rather than route-specific business logic.

5. Local daemon for long-running work

server/cabinet-daemon.ts is the second major runtime. It handles WebSocket-style live communication, scheduled work, structured agent execution, and terminal/session management. The daemon is the boundary for things that should not be tied to request/response HTTP lifecycles: agent runs, heartbeats, live output streaming, and scheduler-driven jobs.

6. Agent runtime

Agent behavior is built around a provider adapter layer in src/lib/agents. This abstracts different CLI runtimes and model providers such as Claude Code, Codex CLI, Cursor, Gemini, OpenCode, and others. The system supports local/CLI-based execution, streaming transcripts, per-run overrides, action parsing/validation, and conversation persistence so agent runs can be replayed in the UI.

7. Agent work products

Agents are not just chat sessions; they produce several distinct artifacts: conversations, tasks, jobs, heartbeats, inbox drafts, and scheduled routines. These artifacts are surfaced through dedicated pages and API routes under src/app/api/agents/* and rendered by specialized components in src/components/agents, src/components/tasks, and related panels. That separation is important: the UI views are distinct, but they all consume the same agent/conversation/task domain objects.

8. Knowledge base editing and rendering

Editing is centered on Tiptap-based rich text with markdown round-tripping, embedded media, tables, code blocks, and custom viewers. The app also has specialized viewers for PDFs, Office files, HTML apps, notebooks, Google Docs, images, and source files. This makes the content layer more of a document platform than a plain note editor.

9. Filesystem, history, and navigation

The storage layer under src/lib/storage, src/lib/history, src/lib/git, and src/lib/navigation manages path conventions, references, rename undo, page I/O, diffs, and restore flows. Cabinet treats filesystem operations as first-class application events, so features like file history, page restore, and link updates are part of the core architecture rather than add-ons.

10. Search and indexing

Search is split between live UI search and background indexing. src/lib/search and server/search support index building, watcher-based updates, and search services across the local cabinet workspace. This is how Cabinet provides fast global search over a changing file tree without relying on a remote index.

11. Integrations and connectors

External integrations are handled as separate subsystems, not as generic plugins. There are explicit modules and API surfaces for Gmail, Google Drive, Apple Notes import, Notion import, GitHub repo linking, Microsoft login, Telegram, Discord, and MCP catalogs/providers. Some of these are read/write connectors, others are setup/verification flows, but they all plug into the same local data model.

12. Authentication, telemetry, and system services

Auth is a single local password gate with PBKDF2-based cookies and rate limiting; it protects the whole UI/API when enabled. Telemetry is anonymous and local-first, with explicit settings and a local queue/flusher. System routes cover backups, diagnostics, updates, data-dir management, file creation, symlink operations, and install metadata, which makes the app behave like a managed desktop product rather than just a website.

13. CLI/bootstrap and packaging

The cabinetai package is the operational CLI: create, run, update, uninstall, doctor, import, and scaffold. It downloads and manages the app under the user’s home directory and coordinates release manifests and health checks. Electron packaging is present as a desktop distribution layer, but the source architecture is still “local web app + daemon + CLI.”

14. Specialized sidecar services

The mcps/mcp-telegram and mcps/mcp-discord packages are separate adapter processes for chat-platform control/integration. They bridge external messaging systems into Cabinet’s agent/tooling model without collapsing those protocols into the main app process. That keeps chat automation and remote control isolated from the core editor/KB/runtime.

15. Primary flow to draw

The main flow is: user interacts with the Next.js UI → API routes call local domain libraries → those libraries read/write files, git, and local state → the daemon handles long-running agent runs, terminal sessions, and scheduling → results are persisted back into the cabinet files and surfaced again in the UI. That loop is the central architecture of the repo.