# remilianyaa/weavecode architecture

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

- Interactive diagram: https://gitdiagram.com/remilianyaa/weavecode
- Repository: https://github.com/remilianyaa/weavecode

## Overview

WeaveCode is a local AI-agent system centered on a long-running core daemon; the CLI and TUI are clients. The main workflow sends a goal or session message over TCP, runs an agent loop that calls a model and tools under permission checks, and returns results while persisting session and event data. The graph also includes documented MCP, skills, subagents, compaction, and trace capabilities. Some subsystem connections follow the README because their implementation was not sampled; uncertain wiring is omitted.

Main entry points: [`src/weavecode/core/loop.py`](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/loop.py) (Agent loop), [`src/weavecode/core/app.py`](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/app.py) (Core daemon), [`src/weavecode/core/tools/registry.py`](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/tools/registry.py) (Tool registry), [`src/weavecode/core/transport/socket_client.py`](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/transport/socket_client.py) (Socket client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_tui["Terminal UI<br/>[app.py]"]
  node_client["Socket client<br/>[socket_client.py]"]
end

subgraph group_core["Daemon runtime"]
  node_daemon["Core daemon<br/>[app.py]"]
  node_server["Socket server<br/>[socket_server.py]"]
  node_sessions["Session manager<br/>[manager.py]"]
  node_runner["Agent runner<br/>[runner.py]"]
  node_events["Event bus<br/>[bus.py]"]
  node_broadcaster["Event broadcaster<br/>[ipc_broadcaster.py]"]
end

subgraph group_agent["Agent capabilities"]
  node_loop["Agent loop<br/>[loop.py]"]
  node_context["Prompt context<br/>[context.py]"]
  node_tools["Tool registry<br/>[registry.py]"]
  node_builtin["Built-in tools"]
  node_permissions["Permission manager<br/>[manager.py]"]
  node_compact["Context compactor<br/>[compactor.py]"]
  node_skills["Skills loader<br/>[loader.py]"]
  node_subagent["Subagents"]
end

subgraph group_state["Persistence"]
  node_trace["Trace writer<br/>[writer.py]"]
  node_eventwriter["Event writer<br/>[writer.py]"]
  node_db[("SQLite database<br/>[database.py]")]
  node_sessionstore["Session store<br/>[store.py]"]
end

subgraph group_integrations["External integrations"]
  node_llm["LLM provider<br/>[provider.py]"]
  node_model{{"Model service"}}
  node_mcp["MCP manager<br/>[server.py]"]
  node_mcpservers{{"MCP servers"}}
end

node_user(("User"))

node_user -->|"issues commands"| node_cli
node_user -->|"interacts"| node_tui
node_cli -->|"sends RPC"| node_client
node_tui -->|"sends RPC"| node_client
node_client -->|"TCP JSON-RPC"| node_server
node_server -->|"dispatches requests"| node_daemon
node_daemon -->|"handles session commands"| node_sessions
node_sessions -->|"starts runs"| node_runner
node_runner -->|"runs agent"| node_loop
node_loop -->|"builds prompt"| node_context
node_context -->|"loads skills"| node_skills
node_loop -->|"requests completion"| node_llm
node_llm -->|"calls model"| node_model
node_loop -->|"dispatches tool calls"| node_tools
node_tools -->|"invokes tools"| node_builtin
node_loop -->|"checks tool access"| node_permissions
node_loop -->|"compacts context"| node_compact
node_tools -->|"dispatches subagent tools"| node_subagent
node_tools -.->|"registers MCP tools"| node_mcp
node_mcp -.->|"discovers and calls tools"| node_mcpservers
node_sessions -->|"reads and writes sessions"| node_sessionstore
node_sessionstore -->|"persists data"| node_db
node_permissions -->|"loads and saves rules"| node_db
node_daemon -->|"publishes events"| node_events
node_events -->|"pushes events"| node_broadcaster
node_events -->|"records events"| node_eventwriter
node_eventwriter -->|"persists events"| node_db
node_daemon -->|"records timeline"| node_trace
node_broadcaster -->|"pushes event stream"| node_client

click node_cli "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/cli/main.py"
click node_tui "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/tui/app.py"
click node_client "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/transport/socket_client.py"
click node_daemon "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/app.py"
click node_server "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/transport/socket_server.py"
click node_sessions "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/session/manager.py"
click node_runner "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/runner.py"
click node_loop "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/loop.py"
click node_context "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/context.py"
click node_llm "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/llm/provider.py"
click node_tools "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/tools/registry.py"
click node_builtin "https://github.com/remilianyaa/weavecode/tree/main/src/weavecode/core/tools/builtin"
click node_permissions "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/permissions/manager.py"
click node_compact "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/compact/compactor.py"
click node_skills "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/skills/loader.py"
click node_subagent "https://github.com/remilianyaa/weavecode/tree/main/src/weavecode/core/subagent"
click node_mcp "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/mcp/server.py"
click node_events "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/events/bus.py"
click node_broadcaster "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/transport/ipc_broadcaster.py"
click node_trace "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/trace/writer.py"
click node_eventwriter "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/events/writer.py"
click node_db "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/storage/database.py"
click node_sessionstore "https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/session/store.py"

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_tui,node_client,node_user toneBlue
class node_daemon,node_server,node_sessions,node_runner,node_events,node_broadcaster toneAmber
class node_loop,node_context,node_tools,node_builtin,node_permissions,node_compact,node_skills,node_subagent toneMint
class node_trace,node_eventwriter,node_db,node_sessionstore toneRose
class node_llm,node_model,node_mcp,node_mcpservers toneIndigo
```

## Components

### Client interfaces

- [CLI](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/cli/main.py): `src/weavecode/cli/main.py`
- [Terminal UI](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/tui/app.py): `src/weavecode/tui/app.py`
- [Socket client](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/transport/socket_client.py): `src/weavecode/core/transport/socket_client.py`

### Daemon runtime

- [Core daemon](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/app.py): `src/weavecode/core/app.py`
- [Socket server](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/transport/socket_server.py): `src/weavecode/core/transport/socket_server.py`
- [Session manager](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/session/manager.py): `src/weavecode/core/session/manager.py`
- [Agent runner](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/runner.py): `src/weavecode/core/runner.py`
- [Event bus](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/events/bus.py): `src/weavecode/core/events/bus.py`
- [Event broadcaster](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/transport/ipc_broadcaster.py): `src/weavecode/core/transport/ipc_broadcaster.py`

### Agent capabilities

- [Agent loop](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/loop.py): `src/weavecode/core/loop.py`
- [Prompt context](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/context.py): `src/weavecode/core/context.py`
- [Tool registry](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/tools/registry.py): `src/weavecode/core/tools/registry.py`
- [Built-in tools](https://github.com/remilianyaa/weavecode/tree/main/src/weavecode/core/tools/builtin): `src/weavecode/core/tools/builtin`
- [Permission manager](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/permissions/manager.py): `src/weavecode/core/permissions/manager.py`
- [Context compactor](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/compact/compactor.py): `src/weavecode/core/compact/compactor.py`
- [Skills loader](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/skills/loader.py): `src/weavecode/core/skills/loader.py`
- [Subagents](https://github.com/remilianyaa/weavecode/tree/main/src/weavecode/core/subagent): `src/weavecode/core/subagent`

### Persistence

- [Trace writer](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/trace/writer.py): `src/weavecode/core/trace/writer.py`
- [Event writer](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/events/writer.py): `src/weavecode/core/events/writer.py`
- [SQLite database](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/storage/database.py): `src/weavecode/core/storage/database.py`
- [Session store](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/session/store.py): `src/weavecode/core/session/store.py`

### External integrations

- [LLM provider](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/llm/provider.py): `src/weavecode/core/llm/provider.py`
- **Model service**
- [MCP manager](https://github.com/remilianyaa/weavecode/blob/main/src/weavecode/core/mcp/server.py): `src/weavecode/core/mcp/server.py`
- **MCP servers**

### Other components

- **User**

## Connections

- User → CLI: issues commands
- User → Terminal UI: interacts
- CLI → Socket client: sends RPC
- Terminal UI → Socket client: sends RPC
- Socket client → Socket server: TCP JSON-RPC
- Socket server → Core daemon: dispatches requests
- Core daemon → Session manager: handles session commands
- Session manager → Agent runner: starts runs
- Agent runner → Agent loop: runs agent
- Agent loop → Prompt context: builds prompt
- Prompt context → Skills loader: loads skills
- Agent loop → LLM provider: requests completion
- LLM provider → Model service: calls model
- Agent loop → Tool registry: dispatches tool calls
- Tool registry → Built-in tools: invokes tools
- Agent loop → Permission manager: checks tool access
- Agent loop → Context compactor: compacts context
- Tool registry → Subagents: dispatches subagent tools
- Tool registry → MCP manager: registers MCP tools
- MCP manager → MCP servers: discovers and calls tools
- Session manager → Session store: reads and writes sessions
- Session store → SQLite database: persists data
- Permission manager → SQLite database: loads and saves rules
- Core daemon → Event bus: publishes events
- Event bus → Event broadcaster: pushes events
- Event bus → Event writer: records events
- Event writer → SQLite database: persists events
- Core daemon → Trace writer: records timeline
- Event broadcaster → Socket client: pushes event stream