How hkuds/deepcode works
Purpose and entry points
DeepCode is a local, multi-interface coding-agent system for durable project work: agent turns can inspect/edit code, execute tools, gather verification evidence, and continue as Goals or scheduled Automations. The Python CLI/TUI and Tauri Desktop share canonical local state and the same agent runtime.
• CLI commands and interactive flows: cli/automation_cli.py, cli/exec_cli.py, cli/tui/app.py
• Desktop frontend and native host: desktop/src/main.tsx, desktop/src-tauri/src/main.rs
• Desktop launches a Python App Server sidecar: app_server/__main__.py, app_server/server.py
Application layer: durable work orchestration
core/application is the product-facing control plane over domain state, persistence, runtime execution, and management operations. It owns Projects, Threads/Sessions, Turns, Goals, approvals, workspaces, model configuration, automations, extensions, and projections consumed by clients.
• Main composition/application lifecycle: core/application/application.py, core/application/session_runtime.py
• Turn routing, admission, and execution coordination: core/application/turn_service.py, core/application/execution_coordinator.py, core/application/interactive_turn_router.py
• Domain records define stable concepts and policy inputs: core/domain/thread.py, core/domain/turn.py, core/domain/execution_security.py
Control flow is primarily: client submits a turn or goal → application admits it under a frozen security/execution profile → runtime emits events and durable records → clients replay/project thread state.
Agent runtime and supervised tool execution
The agent kernel resolves context, selected Skills/presets, tools, model calls, repeat protection, pruning, and multi-turn Goal behavior. Its harness is the critical safety boundary for local filesystem, shell, patch, web, and delegated-agent operations.
• Runtime loop and Goal continuation: core/agent_runtime/runner.py, core/agent_runtime/goal_runtime.py
• Tool registration and MCP bridging: core/agent_runtime/tools/registry.py, core/agent_runtime/tools/mcp.py
• Native capability implementations and sandbox/policy enforcement: core/harness/tools/shell.py, core/harness/permissions.py, core/harness/sandbox.py
Approvals suspend and later resume the exact tool request; read-only and explicit deny policies constrain tools. Process ownership, timeout, and cancellation boundaries protect execution.
State, coordination, and events
SQLite-backed persistence is the canonical source for projects, threads, turns/events, executions, workflows, automations, and coordination leases. This enables restart recovery and CLI/Desktop continuity rather than client-local histories.
• Database/migration boundary: core/persistence/database.py, core/persistence/migrations.py
• Thread/event and execution persistence: core/persistence/thread_repository.py, core/persistence/event_repository.py, core/persistence/execution_repository.py
• Event contracts and in-process observability: core/events/protocol.py, core/observability/bus.py
Model, Skills, Plugins, and MCP integrations
Provider adapters route inference to configured LLM endpoints while credentials remain in private storage. Skills and Plugins supply bounded instructions/capabilities without widening session permissions. MCP supports external tool servers through managed lifecycle and policy narrowing.
• Provider catalog, credentials, and OpenAI-compatible transport: core/providers/catalog_service.py, core/providers/credentials.py, core/providers/openai_compat.py
• Skill discovery/composition/runtime: core/skills/host.py, core/skills/aggregation.py, core/skills/runtime.py
• MCP connection/runtime and OAuth: core/mcp/runtime.py, core/mcp/connection.py, core/mcp/oauth.py
• Plugin validation/hosting: core/plugins/host.py, core/plugins/formats/agent_plugins_v1.py
External services include user-configured OpenAI, Anthropic, OpenRouter, Ollama/vLLM-compatible, and other LLM endpoints; MCP servers may use stdio, SSE, or Streamable HTTP.
Client and transport boundaries
The App Server exposes a typed local protocol for Desktop; it dispatches operations into the same application services used by CLI. The React Desktop renders projected sessions, workbench data, approvals, management, and automation interfaces; Tauri manages the Python sidecar.
• Protocol codec/models/method dispatch: app_server/protocol/codec.py, app_server/protocol/models.py, app_server/dispatcher.py
• Desktop RPC client/generated protocol: desktop/src/rpc/tauriRuntime.ts, desktop/src/generated/app-server.ts
• Workspace and thread UI: desktop/src/app/useWorkspaceController.ts, desktop/src/features/thread/ThreadConversation.tsx
• Sidecar lifecycle: desktop/src-tauri/src/sidecar.rs, desktop/src-tauri/src/lib.rs
Specialized Paper2Code workflows
The original research-oriented pipeline remains a separate orchestration layer for document/paper ingestion, requirements analysis, planning, reference/code indexing, implementation, and review/verification. It reuses LLM and tool infrastructure but preserves specialist workflow stages.
• Orchestration and workflow context: workflows/agent_orchestration_engine.py, workflows/workflow_context.py
• Planning/review runtime: workflows/planning_runtime.py, workflows/plan_review_runtime.py
• Document/code implementation agents: workflows/agents/document_segmentation_agent.py, workflows/agents/code_implementation_agent.py
Main entry points: runner.py Agent runner · application.py Application lifecycle · execution_coordinator.py Execution coordinator · agent_orchestration_engine.py Paper2Code orchestration
Components 22
Client Interfaces
- CLI and TUI
cli/tui/app.py - Desktop UI
desktop/src/main.tsx - Tauri host · Owns the Python sidecar lifecycle.
desktop/src-tauri/src/sidecar.rs - App Server · Dispatches Desktop operations to shared application services.
app_server/server.py
Application Control Plane
- Application lifecycle · Composes durable work services and session runtime.
core/application/application.py - Turn admission · Freezes execution/security policy before routing work.
core/application/turn_service.py - Execution coordinator
core/application/execution_coordinator.py - Domain policy · Defines threads, turns, and execution security inputs.
core/domain/execution_security.py
Agent Execution
- Agent runner · Resolves context, tools, model calls, pruning, and repeat protection.
core/agent_runtime/runner.py - Goal runtime · Continues durable multi-turn Goals.
core/agent_runtime/goal_runtime.py - Tool registry and MCP bridge
core/agent_runtime/tools/registry.py - Supervised tool harness · Enforces permissions and sandboxing for local capabilities.
core/harness/permissions.py
Durable State
- SQLite database · Stores projects, threads, events, executions, workflows, automations, and leases.
core/persistence/database.py - Thread and event repositories
core/persistence/event_repository.py - In-process event bus
core/observability/bus.py
Models and Extensions
- Model providers · Routes inference while keeping credentials private.
core/providers/catalog_service.py - Skills runtime · Supplies bounded instructions and capabilities.
core/skills/runtime.py - MCP runtime · Manages external tool-server connections under narrowed policy.
core/mcp/runtime.py - Plugin host
core/plugins/host.py
Paper2Code
- Paper2Code orchestration · Coordinates document-to-code workflow stages.
workflows/agent_orchestration_engine.py - Planning and review
workflows/planning_runtime.py - Code implementation agent
workflows/agents/code_implementation_agent.py
Connections 24
- CLI and TUI → Application lifecycle: uses
- Desktop UI → Tauri host: runs through
- Tauri host → App Server: launches sidecar
- Desktop UI → App Server: typed local RPC
- App Server → Application lifecycle: dispatches operations
- Application lifecycle → Turn admission: routes turns
- Turn admission → Domain policy: applies policy
- Turn admission → Execution coordinator: admits work
- Execution coordinator → Agent runner: executes turns
- Agent runner → Goal runtime: continues goals
- Agent runner → Tool registry and MCP bridge: selects tools
- Tool registry and MCP bridge → Supervised tool harness: executes native tools
- Tool registry and MCP bridge → MCP runtime: bridges external tools
- Agent runner → Model providers: requests inference
- Agent runner → Skills runtime: composes skills
- Application lifecycle → Plugin host: hosts extensions
- Application lifecycle → SQLite database: persists canonical state
- Execution coordinator → Thread and event repositories: records execution events
- Thread and event repositories → SQLite database: stores in
- Execution coordinator → In-process event bus: publishes events
- Paper2Code orchestration → Planning and review: plans and reviews
- Planning and review → Code implementation agent: drives implementation
- Paper2Code orchestration → Agent runner: reuses agent runtime
- Paper2Code orchestration → SQLite database: persists workflow state