Skip to content

Commit d45b138

Browse files
committed
refactor: split into multi-crate workspace
Restructure from a single crate into six workspace crates under crates/: - core: platform-independent library (agent, memory, config, security) - cli: binary with clap CLI, desktop GUI, and dangerous tools - server: HTTP/WebSocket API and Telegram bot - sandbox: Landlock/Seatbelt process sandboxing - mobile: UniFFI bindings placeholder for iOS/Android - gen: Bevy 3D scene generation binary (moved from gen/) Safe tools (memory_search, memory_get, web_fetch, web_search) live in core, while dangerous tools (bash, read/write/edit_file) are CLI-only via agent.extend_tools(). This enables core to compile for mobile targets without platform-specific dependencies.
1 parent 9ff216e commit d45b138

93 files changed

Lines changed: 1582 additions & 1312 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

CLAUDE.md

Lines changed: 44 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -29,34 +29,61 @@ cargo fmt --check
2929

3030
LocalGPT is a local-only AI assistant with persistent markdown-based memory and optional autonomous operation via heartbeat.
3131

32-
### Core Modules (`src/`)
32+
The project is structured as a Rust workspace with multiple crates:
33+
34+
```
35+
crates/
36+
├── core/ # localgpt-core — shared library (agent, memory, config, security)
37+
├── cli/ # localgpt-cli — binary with clap CLI, desktop GUI, dangerous tools
38+
├── server/ # localgpt-server — HTTP/WebSocket API and Telegram bot
39+
├── sandbox/ # localgpt-sandbox — Landlock/Seatbelt process sandboxing
40+
├── mobile/ # localgpt-mobile — UniFFI bindings for iOS/Android (placeholder)
41+
└── gen/ # localgpt-gen — Bevy 3D scene generation binary
42+
```
43+
44+
### Core (`crates/core/``localgpt-core`)
45+
46+
Platform-independent library with zero platform-specific deps. Compiles for iOS/Android targets.
3347

3448
- **agent/** - LLM interaction layer
3549
- `providers.rs` - Trait `LLMProvider` with implementations for OpenAI, Anthropic, Ollama, Claude CLI, and GLM (Z.AI). Model prefix determines provider (`claude-cli/*` → Claude CLI, `gpt-*` → OpenAI, `claude-*` → Anthropic API, `glm-*` → GLM, else Ollama)
3650
- `session.rs` - Conversation state with automatic compaction when approaching context window limits
3751
- `session_store.rs` - Session metadata store (`sessions.json`) with CLI session ID persistence
3852
- `system_prompt.rs` - Builds system prompt with identity, safety, workspace info, tools, skills, and special tokens
3953
- `skills.rs` - Loads SKILL.md files from workspace/skills/ for specialized task handling
40-
- `tools.rs` - Agent tools: `bash`, `read_file`, `write_file`, `edit_file`, `memory_search`, `memory_get`, `web_fetch`
54+
- `tools/mod.rs` - Safe tools only: `memory_search`, `memory_get`, `web_fetch`, `web_search`
55+
- **memory/** - Markdown-based knowledge store (SQLite FTS5, file watcher, workspace templates)
56+
- **heartbeat/** - Autonomous task runner on configurable interval
57+
- **config/** - TOML configuration at `~/.localgpt/config.toml`
58+
- **commands.rs** - Shared slash command definitions used by CLI and Telegram
59+
- **concurrency/** - TurnGate and WorkspaceLock
60+
- **paths.rs** - XDG directory resolution
61+
- **security/** - LocalGPT.md policy signing/verification
4162

42-
- **memory/** - Markdown-based knowledge store
43-
- `index.rs` - SQLite FTS5 index for fast search. Chunks files (~400 tokens with 80 token overlap)
44-
- `watcher.rs` - File system watcher for automatic reindexing
45-
- `workspace.rs` - Auto-creates workspace templates on first run (MEMORY.md, HEARTBEAT.md, SOUL.md, .gitignore)
46-
- Files: `MEMORY.md` (curated knowledge), `HEARTBEAT.md` (pending tasks), `memory/YYYY-MM-DD.md` (daily logs)
63+
### CLI (`crates/cli/``localgpt-cli`)
4764

48-
- **heartbeat/** - Autonomous task runner
49-
- `runner.rs` - Runs on configurable interval within active hours. Reads `HEARTBEAT.md` and executes pending tasks
65+
Binary crate. Adds dangerous tools (bash, read_file, write_file, edit_file) via `tools.rs` and `agent.extend_tools()`.
5066

51-
- **server/** - HTTP/WebSocket API and Telegram bot
52-
- `http.rs` - Axum-based REST API. Note: creates new Agent per request (no session persistence via HTTP)
53-
- `telegram.rs` - Telegram bot interface with one-time pairing auth, per-chat sessions, streaming responses with debounced message edits (2s), and full tool support
54-
- Endpoints: `/health`, `/api/status`, `/api/chat`, `/api/memory/search`, `/api/memory/stats`
67+
- **cli/** - Clap subcommands: chat, ask, daemon, memory, config, etc.
68+
- **tools.rs** - CLI-only tools with sandbox integration
69+
- **desktop/** - Optional eframe/egui desktop GUI (feature `desktop`)
5570

56-
- **config/** - TOML configuration at `~/.localgpt/config.toml`
57-
- Supports `${ENV_VAR}` expansion in API keys
58-
- `workspace_path()` returns expanded memory workspace path
59-
- `migrate.rs` - Auto-migrates from OpenClaw's `~/.openclaw/config.json5` if LocalGPT config doesn't exist
71+
### Server (`crates/server/``localgpt-server`)
72+
73+
- **http.rs** - Axum REST API with embedded Web UI
74+
- **telegram.rs** - Telegram bot with pairing auth, streaming, per-chat sessions
75+
76+
### Sandbox (`crates/sandbox/``localgpt-sandbox`)
77+
78+
- Process sandboxing: Landlock (Linux), Seatbelt (macOS)
79+
- Policy builder, capability detection, sandbox child exec
80+
81+
### Key Patterns
82+
83+
- `Agent::new()` creates safe tools only; CLI extends with `agent.extend_tools(create_cli_tools())`
84+
- `Agent::new_with_tools()` for fully custom tool sets (Gen mode)
85+
- Agent is not `Send+Sync` due to SQLite — HTTP handler uses `spawn_blocking`
86+
- Session compaction triggers memory flush before truncating
6087

6188
- **commands.rs** - Shared slash command definitions used by both CLI chat and Telegram bot
6289

Cargo.lock

Lines changed: 86 additions & 19 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)