# ludovicweber87/kepler architecture

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

- Interactive diagram: https://gitdiagram.com/ludovicweber87/kepler
- Repository: https://github.com/ludovicweber87/kepler

## Overview

Kepler is a local-first Mac application for coordinating multiple Claude Code agents, each in an isolated project worktree. The main workflow is to configure a persona and start an agent, optionally from a GitHub issue; Kepler prepares a worktree, drives the Claude Agent SDK, and presents chat, activity, file changes, and notifications. Separate product areas cover GitHub issue/PR management, task tracking, documentation, and daily recaps. The graph combines README-documented capabilities with source-index and excerpt evidence; several unsampled subsystem links are documented rather than inferred from names.

Main entry points: [`packages/agent/src/terminal.ts`](https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/terminal.ts) (Agent server), [`src/db/index.ts`](https://github.com/ludovicweber87/kepler/blob/main/src/db/index.ts) (SQLite database), [`src/app/api/agent-sessions/route.ts`](https://github.com/ludovicweber87/kepler/blob/main/src/app/api/agent-sessions/route.ts) (Agent sessions API), [`packages/agent/src/sdk/sdkAgent.ts`](https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/sdk/sdkAgent.ts) (Claude SDK driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_ui["Kepler UI<br/>[AppShell.tsx]"]
  node_workbench["Agent workbench<br/>[Workbench.tsx]"]
  node_chat["Agent chat<br/>[AgentChatTab.tsx]"]
  node_taskhook["Task data hook<br/>[useTasks.ts]"]
end

subgraph group_agents["Agent runtime"]
  node_agentserver["Agent server<br/>[terminal.ts]"]
  node_sdk["Claude SDK driver<br/>[sdkAgent.ts]"]
  node_worktrees["Worktree setup<br/>[branches.ts]"]
end

subgraph group_work["Project workflows"]
  node_personas["Personas<br/>[route.ts]"]
  node_githubui["Issues and PRs<br/>[IssueDetail.tsx]"]
  node_tasks["Task tracking<br/>[TasksPage.tsx]"]
  node_docs["Documentation<br/>[docSession.ts]"]
  node_recaps["Daily recaps<br/>[route.ts]"]
  node_notifications["Notifications<br/>[insert.ts]"]
end

subgraph group_services["Local services"]
  node_agentapi["Agent sessions API<br/>[route.ts]"]
  node_githubapi["GitHub integration<br/>[github.ts]"]
  node_taskroute["Tasks API<br/>[route.ts]"]
end

subgraph group_state["Local state"]
  node_database[("SQLite database<br/>[index.ts]")]
  node_schema["Application schema<br/>[schema.ts]"]
end

node_person(("User"))
node_claude(("Claude Code"))
node_github(("GitHub"))

node_person -->|"uses"| node_ui
node_ui -->|"opens sessions"| node_workbench
node_workbench -->|"shows conversation"| node_chat
node_chat -.->|"streams session"| node_agentapi
node_agentapi -.->|"manages sessions"| node_agentserver
node_agentserver -->|"drives agent"| node_sdk
node_sdk -->|"uses Agent SDK"| node_claude
node_agentserver -->|"prepares worktree"| node_worktrees
node_person -->|"configures persona"| node_personas
node_personas -->|"sets agent instructions"| node_sdk
node_githubui -.->|"requests issue data"| node_githubapi
node_githubapi -->|"reads and updates"| node_github
node_githubui -->|"starts issue work"| node_agentserver
node_tasks -->|"manages tasks"| node_taskhook
node_taskhook -->|"calls tasks API"| node_taskroute
node_taskroute -->|"reads and writes"| node_database
node_docs -->|"writes documents"| node_claude
node_recaps -->|"generates summaries"| node_claude
node_agentserver -->|"notifies activity"| node_notifications
node_notifications -.->|"stores notifications"| node_database
node_agentapi -->|"reads and writes sessions"| node_database
node_database -->|"uses definitions"| node_schema

click node_ui "https://github.com/ludovicweber87/kepler/blob/main/src/components/layout/AppShell.tsx"
click node_workbench "https://github.com/ludovicweber87/kepler/blob/main/src/components/workbench/Workbench.tsx"
click node_chat "https://github.com/ludovicweber87/kepler/blob/main/src/components/agents/AgentChatTab.tsx"
click node_agentapi "https://github.com/ludovicweber87/kepler/blob/main/src/app/api/agent-sessions/route.ts"
click node_agentserver "https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/terminal.ts"
click node_sdk "https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/sdk/sdkAgent.ts"
click node_worktrees "https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/branches.ts"
click node_personas "https://github.com/ludovicweber87/kepler/blob/main/src/app/api/personas/route.ts"
click node_githubui "https://github.com/ludovicweber87/kepler/blob/main/src/components/dashboard/IssueDetail.tsx"
click node_githubapi "https://github.com/ludovicweber87/kepler/blob/main/src/lib/github.ts"
click node_tasks "https://github.com/ludovicweber87/kepler/blob/main/src/components/tasks/TasksPage.tsx"
click node_taskhook "https://github.com/ludovicweber87/kepler/blob/main/src/hooks/useTasks.ts"
click node_taskroute "https://github.com/ludovicweber87/kepler/blob/main/src/app/api/tasks/route.ts"
click node_docs "https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/sdk/docSession.ts"
click node_recaps "https://github.com/ludovicweber87/kepler/blob/main/src/app/api/recaps/route.ts"
click node_notifications "https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/notifications/insert.ts"
click node_database "https://github.com/ludovicweber87/kepler/blob/main/src/db/index.ts"
click node_schema "https://github.com/ludovicweber87/kepler/blob/main/src/db/schema.ts"

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_ui,node_workbench,node_chat,node_taskhook,node_person toneBlue
class node_agentserver,node_sdk,node_worktrees toneAmber
class node_personas,node_githubui,node_tasks,node_docs,node_recaps,node_notifications toneMint
class node_agentapi,node_githubapi,node_taskroute toneRose
class node_database,node_schema,node_claude,node_github toneIndigo
```

## Components

### Desktop interface

- [Kepler UI](https://github.com/ludovicweber87/kepler/blob/main/src/components/layout/AppShell.tsx): `src/components/layout/AppShell.tsx`
- [Agent workbench](https://github.com/ludovicweber87/kepler/blob/main/src/components/workbench/Workbench.tsx): `src/components/workbench/Workbench.tsx`
- [Agent chat](https://github.com/ludovicweber87/kepler/blob/main/src/components/agents/AgentChatTab.tsx): `src/components/agents/AgentChatTab.tsx`
- [Task data hook](https://github.com/ludovicweber87/kepler/blob/main/src/hooks/useTasks.ts): `src/hooks/useTasks.ts`

### Agent runtime

- [Agent server](https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/terminal.ts): `packages/agent/src/terminal.ts`
- [Claude SDK driver](https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/sdk/sdkAgent.ts): `packages/agent/src/sdk/sdkAgent.ts`
- [Worktree setup](https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/branches.ts): `packages/agent/src/branches.ts`

### Project workflows

- [Personas](https://github.com/ludovicweber87/kepler/blob/main/src/app/api/personas/route.ts): `src/app/api/personas/route.ts`
- [Issues and PRs](https://github.com/ludovicweber87/kepler/blob/main/src/components/dashboard/IssueDetail.tsx): `src/components/dashboard/IssueDetail.tsx`
- [Task tracking](https://github.com/ludovicweber87/kepler/blob/main/src/components/tasks/TasksPage.tsx): `src/components/tasks/TasksPage.tsx`
- [Documentation](https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/sdk/docSession.ts): `packages/agent/src/sdk/docSession.ts`
- [Daily recaps](https://github.com/ludovicweber87/kepler/blob/main/src/app/api/recaps/route.ts): `src/app/api/recaps/route.ts`
- [Notifications](https://github.com/ludovicweber87/kepler/blob/main/packages/agent/src/notifications/insert.ts): `packages/agent/src/notifications/insert.ts`

### Local services

- [Agent sessions API](https://github.com/ludovicweber87/kepler/blob/main/src/app/api/agent-sessions/route.ts): `src/app/api/agent-sessions/route.ts`
- [GitHub integration](https://github.com/ludovicweber87/kepler/blob/main/src/lib/github.ts): `src/lib/github.ts`
- [Tasks API](https://github.com/ludovicweber87/kepler/blob/main/src/app/api/tasks/route.ts): `src/app/api/tasks/route.ts`

### Local state

- [SQLite database](https://github.com/ludovicweber87/kepler/blob/main/src/db/index.ts): `src/db/index.ts`
- [Application schema](https://github.com/ludovicweber87/kepler/blob/main/src/db/schema.ts): `src/db/schema.ts`

### Other components

- **User**
- **Claude Code**
- **GitHub**

## Connections

- User → Kepler UI: uses
- Kepler UI → Agent workbench: opens sessions
- Agent workbench → Agent chat: shows conversation
- Agent chat → Agent sessions API: streams session
- Agent sessions API → Agent server: manages sessions
- Agent server → Claude SDK driver: drives agent (evidence: `packages/agent/src/terminal.ts`)
- Claude SDK driver → Claude Code: uses Agent SDK
- Agent server → Worktree setup: prepares worktree
- User → Personas: configures persona
- Personas → Claude SDK driver: sets agent instructions
- Issues and PRs → GitHub integration: requests issue data
- GitHub integration → GitHub: reads and updates
- Issues and PRs → Agent server: starts issue work
- Task tracking → Task data hook: manages tasks (evidence: `src/components/tasks/TasksPage.tsx`)
- Task data hook → Tasks API: calls tasks API (evidence: `src/hooks/useTasks.ts`)
- Tasks API → SQLite database: reads and writes (evidence: `src/app/api/tasks/route.ts`)
- Documentation → Claude Code: writes documents
- Daily recaps → Claude Code: generates summaries
- Agent server → Notifications: notifies activity
- Notifications → SQLite database: stores notifications
- Agent sessions API → SQLite database: reads and writes sessions (evidence: `src/app/api/agent-sessions/route.ts`)
- SQLite database → Application schema: uses definitions (evidence: `src/db/index.ts`)
