# akhtarshadab/deepseek-harness architecture

> Architecture diagram of the GitHub repository akhtarshadab/deepseek-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akhtarshadab/deepseek-harness
- Repository: https://github.com/akhtarshadab/deepseek-harness

## Overview

DeepSeek Harness is a plugin-oriented agent harness with a local Web UI and CLI entry point. Its main user workflow is composing a prompt, managing a session, and observing the agent conversation; session and workspace APIs provide the control layer between client features and runtime behavior. The repository also exposes SDK and ACP interfaces, attachments, session search/export, and an experimental inspector. Several runtime areas are represented only by the tree or documentation, so the graph shows those capabilities without asserting undocumented call chains.

Main entry points: [`packages/api/session-controller/src/client/sessions/manager.ts`](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/client/sessions/manager.ts) (Session manager), [`packages/api/session-controller/src/agent.ts`](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/agent.ts) (Agent control), [`packages/sdk/server/src/server.ts`](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/sdk/server/src/server.ts) (SDK JSON-RPC), [`apps/web/src/main.ts`](https://github.com/akhtarshadab/deepseek-harness/blob/master/apps/web/src/main.ts) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[bin.ts]"]
  node_web["Web app<br/>[main.ts]"]
  node_webbundle["Web bundle<br/>[startup.ts]"]
end

subgraph group_client["Client experience"]
  node_composer["Conversation UI<br/>[InputBar.tsx]"]
  node_chat["Chat transcript<br/>[ChatView.tsx]"]
  node_connection["Client connection<br/>[connection.ts]"]
end

subgraph group_control["Session control"]
  node_sessionmanager["Session manager<br/>[manager.ts]"]
  node_sessionapi["Session API<br/>[index.ts]"]
  node_workspace["Workspace API<br/>[index.ts]"]
  node_agent["Agent control<br/>[agent.ts]"]
end

subgraph group_runtime["Agent interfaces"]
  node_runtime["Harness runtime<br/>[index.ts]"]
  node_sdk["SDK JSON-RPC<br/>[server.ts]"]
  node_acp["ACP protocol<br/>[index.ts]"]
end

subgraph group_capabilities["Supporting capabilities"]
  node_attachments["Attachment handling<br/>[index.ts]"]
  node_sessionquery["Session search<br/>[query.ts]"]
  node_logexport["Log export<br/>[controller.ts]"]
  node_inspectorhost["Inspector host<br/>[controller.ts]"]
  node_inspectorworker["Inspector queries<br/>[query-router.ts]"]
  node_inspectorclient["Inspector client<br/>[controller.ts]"]
  node_landlock["Linux sandbox<br/>[main.c]"]
end

node_user(("User"))

node_user -->|"launches"| node_cli
node_user -->|"uses"| node_web
node_web -->|"starts"| node_webbundle
node_user -->|"composes prompt"| node_composer
node_composer -->|"submits via"| node_connection
node_connection -->|"transports requests"| node_sessionmanager
node_sessionmanager -->|"uses session control"| node_sessionapi
node_sessionmanager -->|"provides session view"| node_chat
node_sessionapi -->|"controls agent"| node_agent
node_agent -->|"operates in"| node_runtime
node_sdk -->|"submits followups"| node_agent
node_sdk -->|"admits images"| node_attachments
node_acp -.->|"protocol integration"| node_runtime
node_user -->|"searches sessions"| node_sessionquery
node_user -->|"downloads logs"| node_logexport
node_inspectorhost -->|"dispatches queries"| node_inspectorworker
node_inspectorclient -->|"connects to"| node_inspectorhost

click node_cli "https://github.com/akhtarshadab/deepseek-harness/blob/master/apps/cli/src/bin.ts"
click node_web "https://github.com/akhtarshadab/deepseek-harness/blob/master/apps/web/src/main.ts"
click node_webbundle "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/bundle/web-app/src/startup.ts"
click node_composer "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx"
click node_chat "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/client/ui-chat/src/client/chat/ChatView.tsx"
click node_connection "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/client/connection/src/client/connection.ts"
click node_sessionmanager "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/client/sessions/manager.ts"
click node_sessionapi "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/index.ts"
click node_workspace "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/workspace-controller/src/index.ts"
click node_agent "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/agent.ts"
click node_runtime "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/bundle/base/src/index.ts"
click node_sdk "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/sdk/server/src/server.ts"
click node_acp "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/acp/acp/src/index.ts"
click node_attachments "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/attachment/attachment-local/src/index.ts"
click node_sessionquery "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/session-query/session-query-sqlite/src/query.ts"
click node_logexport "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/session-query/session-log-export/src/client/controller.ts"
click node_inspectorhost "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/experimental/inspector/src/host/bridge/controller.ts"
click node_inspectorworker "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/experimental/inspector/src/worker/inspection/query-router.ts"
click node_inspectorclient "https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/experimental/inspector/src/client/bridge/controller.ts"
click node_landlock "https://github.com/akhtarshadab/deepseek-harness/blob/master/native/landlock-run/packages/entry/src/main.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_web,node_webbundle,node_user toneBlue
class node_composer,node_chat,node_connection toneAmber
class node_sessionmanager,node_sessionapi,node_workspace,node_agent toneMint
class node_runtime,node_sdk,node_acp toneRose
class node_attachments,node_sessionquery,node_logexport,node_inspectorhost,node_inspectorworker,node_inspectorclient,node_landlock toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/akhtarshadab/deepseek-harness/blob/master/apps/cli/src/bin.ts): `apps/cli/src/bin.ts`
- [Web app](https://github.com/akhtarshadab/deepseek-harness/blob/master/apps/web/src/main.ts): `apps/web/src/main.ts`
- [Web bundle](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/bundle/web-app/src/startup.ts): `packages/bundle/web-app/src/startup.ts`

### Client experience

- [Conversation UI](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx): `packages/client/ui-conversation/src/client/skeleton/InputBar.tsx`
- [Chat transcript](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/client/ui-chat/src/client/chat/ChatView.tsx): `packages/client/ui-chat/src/client/chat/ChatView.tsx`
- [Client connection](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/client/connection/src/client/connection.ts): `packages/client/connection/src/client/connection.ts`

### Session control

- [Session manager](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/client/sessions/manager.ts): `packages/api/session-controller/src/client/sessions/manager.ts`
- [Session API](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/index.ts): `packages/api/session-controller/src/index.ts`
- [Workspace API](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/workspace-controller/src/index.ts): `packages/api/workspace-controller/src/index.ts`
- [Agent control](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/api/session-controller/src/agent.ts): `packages/api/session-controller/src/agent.ts`

### Agent interfaces

- [Harness runtime](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/bundle/base/src/index.ts): `packages/bundle/base/src/index.ts`
- [SDK JSON-RPC](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/sdk/server/src/server.ts): `packages/sdk/server/src/server.ts`
- [ACP protocol](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/acp/acp/src/index.ts): `packages/acp/acp/src/index.ts`

### Supporting capabilities

- [Attachment handling](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/attachment/attachment-local/src/index.ts): `packages/attachment/attachment-local/src/index.ts`
- [Session search](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/session-query/session-query-sqlite/src/query.ts): `packages/session-query/session-query-sqlite/src/query.ts`
- [Log export](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/session-query/session-log-export/src/client/controller.ts): `packages/session-query/session-log-export/src/client/controller.ts`
- [Inspector host](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/experimental/inspector/src/host/bridge/controller.ts): `packages/experimental/inspector/src/host/bridge/controller.ts`
- [Inspector queries](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/experimental/inspector/src/worker/inspection/query-router.ts): `packages/experimental/inspector/src/worker/inspection/query-router.ts`
- [Inspector client](https://github.com/akhtarshadab/deepseek-harness/blob/master/packages/experimental/inspector/src/client/bridge/controller.ts): `packages/experimental/inspector/src/client/bridge/controller.ts`
- [Linux sandbox](https://github.com/akhtarshadab/deepseek-harness/blob/master/native/landlock-run/packages/entry/src/main.c): `native/landlock-run/packages/entry/src/main.c`

### Other components

- **User**

## Connections

- User → CLI: launches
- User → Web app: uses
- Web app → Web bundle: starts
- User → Conversation UI: composes prompt
- Conversation UI → Client connection: submits via
- Client connection → Session manager: transports requests
- Session manager → Session API: uses session control
- Session manager → Chat transcript: provides session view
- Session API → Agent control: controls agent
- Agent control → Harness runtime: operates in
- SDK JSON-RPC → Agent control: submits followups
- SDK JSON-RPC → Attachment handling: admits images
- ACP protocol → Harness runtime: protocol integration
- User → Session search: searches sessions
- User → Log export: downloads logs
- Inspector host → Inspector queries: dispatches queries
- Inspector client → Inspector host: connects to