How ludovicweber87/kepler works
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: terminal.ts Agent server · index.ts SQLite database · route.ts Agent sessions API · sdkAgent.ts Claude SDK driver
Components 21
Desktop interface
- Kepler UI
src/components/layout/AppShell.tsx - Agent workbench
src/components/workbench/Workbench.tsx - Agent chat
src/components/agents/AgentChatTab.tsx - Task data hook
src/hooks/useTasks.ts
Agent runtime
- Agent server
packages/agent/src/terminal.ts - Claude SDK driver
packages/agent/src/sdk/sdkAgent.ts - Worktree setup
packages/agent/src/branches.ts
Project workflows
- Personas
src/app/api/personas/route.ts - Issues and PRs
src/components/dashboard/IssueDetail.tsx - Task tracking
src/components/tasks/TasksPage.tsx - Documentation
packages/agent/src/sdk/docSession.ts - Daily recaps
src/app/api/recaps/route.ts - Notifications
packages/agent/src/notifications/insert.ts
Local services
- Agent sessions API
src/app/api/agent-sessions/route.ts - GitHub integration
src/lib/github.ts - Tasks API
src/app/api/tasks/route.ts
Local state
- SQLite database
src/db/index.ts - Application schema
src/db/schema.ts
Other components
- User
- Claude Code
- GitHub
Connections 22
- 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
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
src/components/tasks/TasksPage.tsx - Task data hook → Tasks API: calls tasks API
src/hooks/useTasks.ts - Tasks API → SQLite database: reads and writes
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
src/app/api/agent-sessions/route.ts - SQLite database → Application schema: uses definitions
src/db/index.ts