Skip to main content
Pioneer is a Cargo workspace with twenty Rust crates. The split is intentionally direct: public protocol, gateway orchestration, agent execution, hook runtime, provider adapters, tools, artifacts, tasks, MCP, skills, prompt compilation, agent memory, secret storage, and durable storage are separate layers. This page is a map, not the architecture itself. Use it when you need to know where a responsibility lives before reading the deeper page for that layer.

​
Why The Workspace Is Split This Way

The split follows runtime boundaries. Provider code should not know about WebSocket sessions. Prompt compilation should not know about SQLite. Tools should not know which client requested a turn. The gateway is allowed to wire everything together; most other crates should stay focused. That shape keeps changes smaller. Adding a provider should mostly touch provider and gateway provider listing/key handling, with secret values routed through keystore. Changing prompt section ordering should mostly touch promt and prompt tests. Adding a task event should touch protocol, tasks, crud, and gateway notifications, but not desktop-specific execution code.

​
Workspace Crates

CrateKindResponsibility
crates/gatewaybinary + libraryMain service. Owns WebSocket JSON-RPC sessions, auth, settings, workspaces, threads, turns, providers, MCP service, skills handlers, task runtime, resilience workers, and persistence coordination.
crates/desktopbinaryNative GPUI desktop client. Connects to gateways, starts/manages a local gateway, and renders conversations, providers, skills, MCP, tasks, and settings.
crates/clibinaryCommand-line utility, service management entry point, token issuance, and keystore maintenance surface.
crates/protocollibraryPublic JSON-RPC contract, request/response types, notification types, domain DTOs, method constants, and schema export.
crates/agentlibraryPer-thread agent runtime, turn execution, provider loop, tool loop, lifecycle hook wiring, MCP/tool/task materialization, skill resolution, recovery handling.
crates/hookslibraryTyped lifecycle hook runtime, hook subscriptions, phase requests, contribution sets, execution/failure policy, dependencies, diagnostics, and hook-run summaries.
crates/artifactslibraryWorkspace-scoped artifact service, blob store abstraction, ingestion, path validation, quotas, GC planning, projections, and provider artifact resolution.
crates/memorylibraryDurable agent memory service, memvid backend integration, recall ranking, semantic writes, canonical keys, candidate policy, tombstones, and repair diagnostics.
crates/keystorelibrarySecret storage facade backed by db-keystore, stable secret ids, metadata, permission hardening, and an in-memory test store.
crates/promtlibraryPrompt compiler. Builds stable and dynamic system prompt sections, reads bootstrap files, applies prompt budgets, emits prompt manifests and fingerprints.
crates/providerlibraryProvider trait, provider registry, provider implementations, streaming/non-streaming chat, tool-call parsing, attachment normalization and upload planning.
crates/toolslibraryBuilt-in tool registry, shell sessions, filesystem tools, patch application, grep, web search/fetch/download, computer use, dynamic tool extension bundles, output policies, retry classification.
crates/taskslibraryDurable task service, scheduler, trigger calculator, executor registry, event bus, projectors, retries, deliveries, write locks, startup reconciliation.
crates/mcplibraryMCP install config parser, validation, secret redaction/materialization, stdio and streamable HTTP clients, runtime connector, catalog snapshots, retry policy.
crates/skillslibraryAgent Skills-compatible contract parser, installer, validation, security scanning, dependency preflight, policy merge, catalog loading, runtime tool declarations, prompt building.
crates/crudlibrarySeaORM-backed repository layer and projectors for turns, items, threads, artifacts, tasks, skills, MCP, recovery jobs, prompt manifests, and LLM context retention.
crates/entitylibrarySeaORM entity definitions generated/maintained for the SQLite schema.
crates/migrationlibrarySeaORM migrations for database schema evolution.
crates/sqlitelibrarySQLite-specific helpers, especially write coordination for concurrent async access.
crates/configlibraryLayered configuration loader for default config, user config, gateway config, install paths, tools, artifacts, provider attachments, skills, database, and auth.

​
Dependency Direction

The important rule is that protocol sits at the public edge while gateway is the integration layer. Lower-level crates should not need to know about desktop UI state. Domain crates expose typed APIs that the gateway wires into request handlers and background runtimes.

​
Where To Look First

QuestionStart here
How does a JSON-RPC method reach a handler?crates/gateway/src/message/dispatch.rs
How does turn/start become an agent run?crates/gateway/src/message/turn_handlers.rs, then crates/agent/src/manager.rs and crates/agent/src/agent_loop.rs
How is the LLM prompt compiled?crates/agent/src/chat/mod.rs, then crates/promt/src/compile/compiler.rs
How are turn lifecycle hooks registered and run?crates/hooks/src/runtime.rs, crates/hooks/src/registry.rs, then crates/agent/src/hooks.rs
How does agent memory recall and write durable facts?crates/memory/src/hooks, crates/gateway/src/memory_runtime.rs, then crates/memory/src/service.rs
How is previous conversation context selected?crates/gateway/src/message/provider_handlers.rs
How are tools exposed to the model?crates/agent/src/chat/mod.rs, crates/tools/src/lib.rs
How are MCP servers installed and called?crates/gateway/src/message/mcp/mod.rs, crates/gateway/src/mcp_service.rs, crates/mcp/src/config.rs
How are secret values stored?crates/keystore/src/lib.rs, crates/gateway/src/secrets.rs, crates/desktop/src/gateway/secrets.rs
How are skills resolved into prompt and tools?crates/agent/src/chat/skills.rs, crates/skills/src/prompt.rs, crates/skills/src/runtime.rs
How do tasks create subagents?crates/gateway/src/message/task_agent_executor.rs, crates/tasks/src/service.rs
How is data persisted?crates/crud/src/lib.rs, crates/crud/src/projector.rs, crates/crud/src/task_projector.rs