Limboo

The operating system for AI software development.

A local-first desktop workspace that gives a connected coding agent everything it needs to do real engineering: projects, sessions, file watching, repository indexing, git, terminals, memory, permissions, and context. Limboo is not an AI model. It is the environment around one.

Documentation · Architecture · Contributing · Roadmap · Security

---

What is Limboo?

Limboo is a desktop application (Electron + React + TypeScript) that acts as the workspace around a coding agent. The agent already understands programming, debugging, planning, and git. Limboo provides the environment where it can perform at its highest level: it manages the repository, watches the filesystem, runs the terminal, owns the database, holds durable project memory, and enforces a strict security boundary, while the agent focuses exclusively on writing software.

Every unit of work is a Session — a bundle of a repository, branch, chat history, agent, terminal history, checkpoints, permissions, context, memory, tasks, and generated files. Instead of opening many windows, everything lives inside one workspace.

Why it exists

Traditional IDEs revolve around files. Limboo revolves around conversations. You do not ask "which file should I edit?" — you say "implement authentication," and the agent figures out the files while Limboo visualizes the process: the streaming reply, the tool calls, the file changes, the git diff, and the running commands.

It is local-first by design. There is no backend and no cloud sync. The only network traffic is the connected coding agent talking to its AI provider. The project, its history, and its memory belong to the developer.

Key features

• Session-centric workspace — repo + branch + chat + agent + terminal + checkpoints + memory, all in one place.
• Coding agent orchestration — drives the Claude Code agent (plan and implement modes) with risk-gated tool approvals, path-guarded to the workspace.
• Deep git engine — status, diff, stage, commit, log, branches, tags, blame, fetch, push, pull, plus lightweight per-session checkpoints for instant recovery.
• Integrated terminal — workspace-scoped PTY sessions; agent commands are mirrored into the terminal view.
• File System Layer — live watch + indexed tree + guarded reads, pushing live git status into the session list.
• Local Memory System — durable, provider-independent project knowledge with fully offline FTS5 / BM25 retrieval, injected into the agent prompt.
• Resume Pipeline — reopening a session revalidates the repository against the state it last saw and hands the agent a structured repository delta (commits, files, symbols, dependency manifests) so it continues against current reality, not a stale transcript. Fully local, bounded git, never blocks switching.
• Unified streaming timeline — one continuous, turn-grouped event stream of the conversation, tool calls, and status.
• Pure-black, dark-only UI — a minimal three-pane shell tuned for a true #000000 background.

What makes Limboo different

Most agent tools stop at "resume the conversation." That restores what the agent said, but not the world it said it in. Limboo treats the environment as a first-class, continuously-maintained system that cooperates with the agent instead of leaving it to rediscover reality on every turn.

• The agent resumes against verified repository reality, not a transcript. The Resume Pipeline is the flagship of this idea. When you reopen a session — after an hour or after three weeks of other people's commits, rebases, and dependency bumps — Limboo revalidates the git worktree against the exact state the session last saw and computes a structured repository delta: commits landed, files changed (with dependency manifests and migrations flagged), symbols added or removed, and which files import what changed. That delta is injected once, before your next prompt, so the agent reconciles its assumptions up front instead of burning turns re-reading the tree. It is fully local, uses only bounded argv-only git, and never blocks you from switching sessions. See the Resume Pipeline.

• Isolation by default. Every session can own its own git worktree — a real isolated checkout and branch — so parallel work never collides, and "continue where I left off" means a specific filesystem, not a shared one.

• The app owns the knowledge, not the model. Durable project memory, the search index, and now a symbol/dependency graph are platform services the app maintains and injects — provider-independent and offline. Memory even references repository symbols, so guidance whose code was deleted is automatically demoted until it reappears.

• A hard security boundary you can trust. The renderer performs nothing: all filesystem, git, shell, and database access lives in the main process behind a single typed IPC bridge with sender validation, deny-by-default permissions, and parameterized SQL throughout. Git never runs through a shell; paths are guarded against traversal; secrets are never stored.

The result: continuation feels genuinely intelligent, because the agent begins each resumed task with an accurate, up-to-date understanding of a living codebase.

Screenshots

A tour of the shell: sessions on the left, the conversation in the center, and the activity rail on the right — every panel below is one click on the rail.

Files — the indexed workspace tree with per-language icons	Changes — live git status with per-file diff stats
Git — stage, commit, history, branches, and checkpoints	Memory — durable project knowledge with tiered proposals
Tasks — the agent's live plan and progress	Terminal — workspace-scoped PTY sessions
Command palette — every command behind Ctrl/Cmd+K	Global search — files, symbols, docs, memory, commits, sessions

Settings — general, appearance, agent, git, memory, and advanced JSON editing in one modal:

Architecture at a glance

 Renderer (Chromium + React)   UI only — it asks, it never performs
        |  window.limboo.*
        v
 Preload (contextBridge)        the only bridge; contextIsolation on, sandbox on
        |  ipcRenderer <-> ipcMain
        v
 Main (Node.js + OS access)     workspaces, sessions, git, terminal, fs, agent,
                                memory, SQLite — every OS-touching capability

Limboo runs three Electron contexts with a hard boundary between them. The renderer holds no business logic; all filesystem, git, shell, database, and agent work lives in the main process and crosses a single typed IPC bridge. See docs/architecture/overview.md.

Tech stack

Layer	Choice
Shell / desktop	Electron 42 (via Electron Forge 7)
Bundler	Vite 5 (@electron-forge/plugin-vite)
UI framework	React 19
Language	TypeScript
Styling	Tailwind CSS v4 (CSS-first, no config)
State	Zustand 5 (slice-per-domain stores)
Database	better-sqlite3 (WAL, FTS5)
Terminal	node-pty (Node-API) + xterm
File watching	chokidar
Coding agent	@anthropic-ai/claude-agent-sdk
Icons	lucide-react

Quick start

Prerequisites

• Node.js 20+ and npm.
• A C/C++ build toolchain for better-sqlite3 (build-essential / Xcode Command Line Tools / MSVC Build Tools depending on platform) — it may compile on install if no matching prebuilt is published. node-pty (pinned to the Node-API 1.2.0-beta line) ships an ABI-stable prebuilt and never compiles.
• The coding agent owns its own authentication. Limboo never stores credentials; it reads the agent's existing sign-in (for example ANTHROPIC_API_KEY or the Claude Code credentials file). See docs/guides/using-the-agent.md.

Run in development

npm install     # installs deps and compiles native modules
npm start       # Electron + Vite dev server (renderer on :5173)

There is no npm run dev — npm start drives both Electron and Vite. Full setup notes live in docs/getting-started/installation.md.

Build installers

npm run package   # package the app (no installers)
npm run make      # platform installers (deb / rpm / zip / squirrel)

Documentation

The documentation is organized as a subsystem, not a single file. Start at the documentation home:

• Getting started — installation, quick start, configuration.
• Concepts — sessions, workspaces, local-first, conversation-first UI.
• Guides — using the agent, git workflow, memory system, terminal, keyboard shortcuts.
• Deep dives — the Resume Pipeline ("continue exactly where you left off") and the other subsystem docs.
• Reference — window.limboo API, IPC channels, settings, design tokens, commands.
• Architecture — overview and per-subsystem documentation under docs/architecture/.
• Operations — release, CI/CD, packaging, and maintenance under docs/operations/.

Two internal references predate this site and remain the deepest source of truth for contributors: CLAUDE.md (the code-level working contract) and project.md (the full product and architecture vision).

Project status

Limboo is at 1.0.0. The desktop foundation and platform services are built: workspaces, sessions with per-session git worktrees, the git engine, the integrated terminal, the File System Layer, agent orchestration, the Local Memory System, the Search Engine, the Resume Pipeline ("continue exactly where you left off"), and a hardened IPC layer over a local SQLite database. Planned work (repository clone/track UI, a standalone permission system, merge-conflict resolution, remote management, stash, and a tree-sitter / vector-embeddings upgrade of the code-intelligence layer) is tracked in ROADMAP.md.

Contributing

Contributions are welcome. Read CONTRIBUTING.md for the development workflow, the process-boundary contract, theme discipline, and the verification steps every change must pass. Please also review the Code of Conduct.

Security

Limboo is local-first with a deliberately small attack surface and defense-in-depth hardening. To report a vulnerability, follow SECURITY.md — please do not open a public issue for security reports.

License

Released under the MIT License. Copyright (c) 2026 BotCoder254.