feat: Add conversational AI assistant panel for project codebase Q&A

Implement a slide-in chat panel that allows users to ask questions about
their codebase using Claude Opus 4.5 with read-only access to project files.

Backend changes:
- Add SQLAlchemy models for conversation persistence (assistant_database.py)
- Create AssistantChatSession with read-only Claude SDK client
- Add WebSocket endpoint for real-time chat streaming
- Include read-only MCP tools: feature_get_stats, feature_get_next, etc.

Frontend changes:
- Add floating action button (bottom-right) to toggle panel
- Create slide-in panel component (400px width)
- Implement WebSocket hook with reconnection logic
- Add keyboard shortcut 'A' to toggle assistant

Key features:
- Read-only access: Only Read, Glob, Grep, WebFetch, WebSearch tools
- Persistent history: Conversations saved to SQLite per project
- Real-time streaming: Text chunks streamed as Claude generates response
- Tool visibility: Shows when assistant is using tools to explore code

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Auto
2026-01-04 14:57:58 +02:00
parent 88951e454a
commit 908754302a
13 changed files with 1657 additions and 6 deletions

View File

@@ -14,6 +14,8 @@ import { AddFeatureForm } from './components/AddFeatureForm'
import { FeatureModal } from './components/FeatureModal'
import { DebugLogViewer } from './components/DebugLogViewer'
import { AgentThought } from './components/AgentThought'
import { AssistantFAB } from './components/AssistantFAB'
import { AssistantPanel } from './components/AssistantPanel'
import { Plus, Loader2 } from 'lucide-react'
import type { Feature } from './lib/types'
@@ -31,6 +33,7 @@ function App() {
const [setupComplete, setSetupComplete] = useState(true) // Start optimistic
const [debugOpen, setDebugOpen] = useState(false)
const [debugPanelHeight, setDebugPanelHeight] = useState(288) // Default height
const [assistantOpen, setAssistantOpen] = useState(false)
const { data: projects, isLoading: projectsLoading } = useProjects()
const { data: features } = useFeatures(selectedProject)
@@ -84,9 +87,17 @@ function App() {
setShowAddFeature(true)
}
// A : Toggle assistant panel (when project selected)
if ((e.key === 'a' || e.key === 'A') && selectedProject) {
e.preventDefault()
setAssistantOpen(prev => !prev)
}
// Escape : Close modals
if (e.key === 'Escape') {
if (showAddFeature) {
if (assistantOpen) {
setAssistantOpen(false)
} else if (showAddFeature) {
setShowAddFeature(false)
} else if (selectedFeature) {
setSelectedFeature(null)
@@ -98,7 +109,7 @@ function App() {
window.addEventListener('keydown', handleKeyDown)
return () => window.removeEventListener('keydown', handleKeyDown)
}, [selectedProject, showAddFeature, selectedFeature, debugOpen])
}, [selectedProject, showAddFeature, selectedFeature, debugOpen, assistantOpen])
// Combine WebSocket progress with feature data
const progress = wsState.progress.total > 0 ? wsState.progress : {
@@ -244,6 +255,21 @@ function App() {
onHeightChange={setDebugPanelHeight}
/>
)}
{/* Assistant FAB and Panel */}
{selectedProject && (
<>
<AssistantFAB
onClick={() => setAssistantOpen(!assistantOpen)}
isOpen={assistantOpen}
/>
<AssistantPanel
projectName={selectedProject}
isOpen={assistantOpen}
onClose={() => setAssistantOpen(false)}
/>
</>
)}
</div>
)
}

View File

@@ -0,0 +1,176 @@
/**
* Assistant Chat Component
*
* Main chat interface for the project assistant.
* Displays messages and handles user input.
*/
import { useState, useRef, useEffect, useCallback } from 'react'
import { Send, Loader2, Wifi, WifiOff } from 'lucide-react'
import { useAssistantChat } from '../hooks/useAssistantChat'
import { ChatMessage } from './ChatMessage'
interface AssistantChatProps {
projectName: string
}
export function AssistantChat({ projectName }: AssistantChatProps) {
const [inputValue, setInputValue] = useState('')
const messagesEndRef = useRef<HTMLDivElement>(null)
const inputRef = useRef<HTMLTextAreaElement>(null)
const hasStartedRef = useRef(false)
// Memoize the error handler to prevent infinite re-renders
const handleError = useCallback((error: string) => {
console.error('Assistant error:', error)
}, [])
const {
messages,
isLoading,
connectionStatus,
start,
sendMessage,
} = useAssistantChat({
projectName,
onError: handleError,
})
// Auto-scroll to bottom on new messages
useEffect(() => {
messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
}, [messages])
// Start the chat session when component mounts (only once)
useEffect(() => {
if (!hasStartedRef.current) {
hasStartedRef.current = true
start()
}
}, [start])
// Focus input when not loading
useEffect(() => {
if (!isLoading) {
inputRef.current?.focus()
}
}, [isLoading])
const handleSend = () => {
const content = inputValue.trim()
if (!content || isLoading) return
sendMessage(content)
setInputValue('')
}
const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
if (e.key === 'Enter' && !e.shiftKey) {
e.preventDefault()
handleSend()
}
}
return (
<div className="flex flex-col h-full">
{/* Connection status indicator */}
<div className="flex items-center gap-2 px-4 py-2 border-b-2 border-[var(--color-neo-border)] bg-[var(--color-neo-bg)]">
{connectionStatus === 'connected' ? (
<>
<Wifi size={14} className="text-[var(--color-neo-done)]" />
<span className="text-xs text-[var(--color-neo-text-secondary)]">Connected</span>
</>
) : connectionStatus === 'connecting' ? (
<>
<Loader2 size={14} className="text-[var(--color-neo-progress)] animate-spin" />
<span className="text-xs text-[var(--color-neo-text-secondary)]">Connecting...</span>
</>
) : (
<>
<WifiOff size={14} className="text-[var(--color-neo-danger)]" />
<span className="text-xs text-[var(--color-neo-text-secondary)]">Disconnected</span>
</>
)}
</div>
{/* Messages area */}
<div className="flex-1 overflow-y-auto bg-[var(--color-neo-bg)]">
{messages.length === 0 ? (
<div className="flex items-center justify-center h-full text-[var(--color-neo-text-secondary)] text-sm">
{isLoading ? (
<div className="flex items-center gap-2">
<Loader2 size={16} className="animate-spin" />
<span>Connecting to assistant...</span>
</div>
) : (
<span>Ask me anything about the codebase</span>
)}
</div>
) : (
<div className="py-4">
{messages.map((message) => (
<ChatMessage key={message.id} message={message} />
))}
<div ref={messagesEndRef} />
</div>
)}
</div>
{/* Loading indicator */}
{isLoading && messages.length > 0 && (
<div className="px-4 py-2 border-t-2 border-[var(--color-neo-border)] bg-[var(--color-neo-bg)]">
<div className="flex items-center gap-2 text-[var(--color-neo-text-secondary)] text-sm">
<div className="flex gap-1">
<span className="w-2 h-2 bg-[var(--color-neo-progress)] rounded-full animate-bounce" style={{ animationDelay: '0ms' }} />
<span className="w-2 h-2 bg-[var(--color-neo-progress)] rounded-full animate-bounce" style={{ animationDelay: '150ms' }} />
<span className="w-2 h-2 bg-[var(--color-neo-progress)] rounded-full animate-bounce" style={{ animationDelay: '300ms' }} />
</div>
<span>Thinking...</span>
</div>
</div>
)}
{/* Input area */}
<div className="border-t-3 border-[var(--color-neo-border)] p-4 bg-white">
<div className="flex gap-2">
<textarea
ref={inputRef}
value={inputValue}
onChange={(e) => setInputValue(e.target.value)}
onKeyDown={handleKeyDown}
placeholder="Ask about the codebase..."
disabled={isLoading || connectionStatus !== 'connected'}
className="
flex-1
neo-input
resize-none
min-h-[44px]
max-h-[120px]
py-2.5
"
rows={1}
/>
<button
onClick={handleSend}
disabled={!inputValue.trim() || isLoading || connectionStatus !== 'connected'}
className="
neo-btn neo-btn-primary
px-4
disabled:opacity-50 disabled:cursor-not-allowed
"
title="Send message"
>
{isLoading ? (
<Loader2 size={18} className="animate-spin" />
) : (
<Send size={18} />
)}
</button>
</div>
<p className="text-xs text-[var(--color-neo-text-secondary)] mt-2">
Press Enter to send, Shift+Enter for new line
</p>
</div>
</div>
)
}

View File

@@ -0,0 +1,35 @@
/**
* Floating Action Button for toggling the Assistant panel
*/
import { MessageCircle, X } from 'lucide-react'
interface AssistantFABProps {
onClick: () => void
isOpen: boolean
}
export function AssistantFAB({ onClick, isOpen }: AssistantFABProps) {
return (
<button
onClick={onClick}
className={`
fixed bottom-6 right-6 z-50
w-14 h-14
flex items-center justify-center
bg-[var(--color-neo-progress)] text-white
border-3 border-[var(--color-neo-border)]
rounded-full
shadow-neo-md
transition-all duration-200
hover:shadow-neo-lg hover:-translate-y-0.5
active:shadow-neo-sm active:translate-y-0.5
${isOpen ? 'rotate-0' : ''}
`}
title={isOpen ? 'Close Assistant (Press A)' : 'Open Assistant (Press A)'}
aria-label={isOpen ? 'Close Assistant' : 'Open Assistant'}
>
{isOpen ? <X size={24} /> : <MessageCircle size={24} />}
</button>
)
}

View File

@@ -0,0 +1,79 @@
/**
* Assistant Panel Component
*
* Slide-in panel container for the project assistant chat.
* Slides in from the right side of the screen.
*/
import { X, Bot } from 'lucide-react'
import { AssistantChat } from './AssistantChat'
interface AssistantPanelProps {
projectName: string
isOpen: boolean
onClose: () => void
}
export function AssistantPanel({ projectName, isOpen, onClose }: AssistantPanelProps) {
return (
<>
{/* Backdrop - click to close */}
{isOpen && (
<div
className="fixed inset-0 bg-black/20 z-40 transition-opacity duration-300"
onClick={onClose}
aria-hidden="true"
/>
)}
{/* Panel */}
<div
className={`
fixed right-0 top-0 bottom-0 z-50
w-[400px] max-w-[90vw]
bg-white
border-l-4 border-[var(--color-neo-border)]
shadow-[-8px_0_0px_rgba(0,0,0,1)]
transform transition-transform duration-300 ease-out
flex flex-col
${isOpen ? 'translate-x-0' : 'translate-x-full'}
`}
role="dialog"
aria-label="Project Assistant"
aria-hidden={!isOpen}
>
{/* Header */}
<div className="flex items-center justify-between px-4 py-3 border-b-3 border-[var(--color-neo-border)] bg-[var(--color-neo-progress)]">
<div className="flex items-center gap-2">
<div className="bg-white border-2 border-[var(--color-neo-border)] p-1.5 shadow-[2px_2px_0px_rgba(0,0,0,1)]">
<Bot size={18} />
</div>
<div>
<h2 className="font-display font-bold text-white">Project Assistant</h2>
<p className="text-xs text-white/80 font-mono">{projectName}</p>
</div>
</div>
<button
onClick={onClose}
className="
neo-btn neo-btn-ghost
p-2
bg-white/20 border-white/40
hover:bg-white/30
text-white
"
title="Close Assistant (Press A)"
aria-label="Close Assistant"
>
<X size={18} />
</button>
</div>
{/* Chat area */}
<div className="flex-1 overflow-hidden">
{isOpen && <AssistantChat projectName={projectName} />}
</div>
</div>
</>
)
}

View File

@@ -0,0 +1,286 @@
/**
* Hook for managing assistant chat WebSocket connection
*/
import { useState, useCallback, useRef, useEffect } from 'react'
import type { ChatMessage, AssistantChatServerMessage } from '../lib/types'
type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error'
interface UseAssistantChatOptions {
projectName: string
onError?: (error: string) => void
}
interface UseAssistantChatReturn {
messages: ChatMessage[]
isLoading: boolean
connectionStatus: ConnectionStatus
conversationId: number | null
start: (conversationId?: number | null) => void
sendMessage: (content: string) => void
disconnect: () => void
clearMessages: () => void
}
function generateId(): string {
return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
}
export function useAssistantChat({
projectName,
onError,
}: UseAssistantChatOptions): UseAssistantChatReturn {
const [messages, setMessages] = useState<ChatMessage[]>([])
const [isLoading, setIsLoading] = useState(false)
const [connectionStatus, setConnectionStatus] = useState<ConnectionStatus>('disconnected')
const [conversationId, setConversationId] = useState<number | null>(null)
const wsRef = useRef<WebSocket | null>(null)
const currentAssistantMessageRef = useRef<string | null>(null)
const reconnectAttempts = useRef(0)
const maxReconnectAttempts = 3
const pingIntervalRef = useRef<number | null>(null)
const reconnectTimeoutRef = useRef<number | null>(null)
// Clean up on unmount
useEffect(() => {
return () => {
if (pingIntervalRef.current) {
clearInterval(pingIntervalRef.current)
}
if (reconnectTimeoutRef.current) {
clearTimeout(reconnectTimeoutRef.current)
}
if (wsRef.current) {
wsRef.current.close()
}
}
}, [])
const connect = useCallback(() => {
// Prevent multiple connection attempts
if (wsRef.current?.readyState === WebSocket.OPEN ||
wsRef.current?.readyState === WebSocket.CONNECTING) {
return
}
setConnectionStatus('connecting')
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
const host = window.location.host
const wsUrl = `${protocol}//${host}/api/assistant/ws/${encodeURIComponent(projectName)}`
const ws = new WebSocket(wsUrl)
wsRef.current = ws
ws.onopen = () => {
setConnectionStatus('connected')
reconnectAttempts.current = 0
// Start ping interval to keep connection alive
pingIntervalRef.current = window.setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: 'ping' }))
}
}, 30000)
}
ws.onclose = () => {
setConnectionStatus('disconnected')
if (pingIntervalRef.current) {
clearInterval(pingIntervalRef.current)
pingIntervalRef.current = null
}
// Attempt reconnection if not intentionally closed
if (reconnectAttempts.current < maxReconnectAttempts) {
reconnectAttempts.current++
const delay = Math.min(1000 * Math.pow(2, reconnectAttempts.current), 10000)
reconnectTimeoutRef.current = window.setTimeout(connect, delay)
}
}
ws.onerror = () => {
setConnectionStatus('error')
onError?.('WebSocket connection error')
}
ws.onmessage = (event) => {
try {
const data = JSON.parse(event.data) as AssistantChatServerMessage
switch (data.type) {
case 'text': {
// Append text to current assistant message or create new one
setMessages((prev) => {
const lastMessage = prev[prev.length - 1]
if (lastMessage?.role === 'assistant' && lastMessage.isStreaming) {
// Append to existing streaming message
return [
...prev.slice(0, -1),
{
...lastMessage,
content: lastMessage.content + data.content,
},
]
} else {
// Create new assistant message
currentAssistantMessageRef.current = generateId()
return [
...prev,
{
id: currentAssistantMessageRef.current,
role: 'assistant',
content: data.content,
timestamp: new Date(),
isStreaming: true,
},
]
}
})
break
}
case 'tool_call': {
// Show tool call as system message
setMessages((prev) => [
...prev,
{
id: generateId(),
role: 'system',
content: `Using tool: ${data.tool}`,
timestamp: new Date(),
},
])
break
}
case 'conversation_created': {
setConversationId(data.conversation_id)
break
}
case 'response_done': {
setIsLoading(false)
// Mark current message as done streaming
setMessages((prev) => {
const lastMessage = prev[prev.length - 1]
if (lastMessage?.role === 'assistant' && lastMessage.isStreaming) {
return [
...prev.slice(0, -1),
{ ...lastMessage, isStreaming: false },
]
}
return prev
})
break
}
case 'error': {
setIsLoading(false)
onError?.(data.content)
// Add error as system message
setMessages((prev) => [
...prev,
{
id: generateId(),
role: 'system',
content: `Error: ${data.content}`,
timestamp: new Date(),
},
])
break
}
case 'pong': {
// Keep-alive response, nothing to do
break
}
}
} catch (e) {
console.error('Failed to parse WebSocket message:', e)
}
}
}, [projectName, onError])
const start = useCallback((existingConversationId?: number | null) => {
connect()
// Wait for connection then send start message
const checkAndSend = () => {
if (wsRef.current?.readyState === WebSocket.OPEN) {
setIsLoading(true)
const payload: { type: string; conversation_id?: number } = { type: 'start' }
if (existingConversationId) {
payload.conversation_id = existingConversationId
setConversationId(existingConversationId)
}
wsRef.current.send(JSON.stringify(payload))
} else if (wsRef.current?.readyState === WebSocket.CONNECTING) {
setTimeout(checkAndSend, 100)
}
}
setTimeout(checkAndSend, 100)
}, [connect])
const sendMessage = useCallback((content: string) => {
if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
onError?.('Not connected')
return
}
// Add user message to chat
setMessages((prev) => [
...prev,
{
id: generateId(),
role: 'user',
content,
timestamp: new Date(),
},
])
setIsLoading(true)
// Send to server
wsRef.current.send(
JSON.stringify({
type: 'message',
content,
})
)
}, [onError])
const disconnect = useCallback(() => {
reconnectAttempts.current = maxReconnectAttempts // Prevent reconnection
if (pingIntervalRef.current) {
clearInterval(pingIntervalRef.current)
pingIntervalRef.current = null
}
if (wsRef.current) {
wsRef.current.close()
wsRef.current = null
}
setConnectionStatus('disconnected')
}, [])
const clearMessages = useCallback(() => {
setMessages([])
setConversationId(null)
}, [])
return {
messages,
isLoading,
connectionStatus,
conversationId,
start,
sendMessage,
disconnect,
clearMessages,
}
}

View File

@@ -14,6 +14,8 @@ import type {
SetupStatus,
DirectoryListResponse,
PathValidationResponse,
AssistantConversation,
AssistantConversationDetail,
} from './types'
const API_BASE = '/api'
@@ -228,3 +230,40 @@ export async function validatePath(path: string): Promise<PathValidationResponse
body: JSON.stringify({ path }),
})
}
// ============================================================================
// Assistant Chat API
// ============================================================================
export async function listAssistantConversations(
projectName: string
): Promise<AssistantConversation[]> {
return fetchJSON(`/assistant/conversations/${encodeURIComponent(projectName)}`)
}
export async function getAssistantConversation(
projectName: string,
conversationId: number
): Promise<AssistantConversationDetail> {
return fetchJSON(
`/assistant/conversations/${encodeURIComponent(projectName)}/${conversationId}`
)
}
export async function createAssistantConversation(
projectName: string
): Promise<AssistantConversation> {
return fetchJSON(`/assistant/conversations/${encodeURIComponent(projectName)}`, {
method: 'POST',
})
}
export async function deleteAssistantConversation(
projectName: string,
conversationId: number
): Promise<void> {
await fetchJSON(
`/assistant/conversations/${encodeURIComponent(projectName)}/${conversationId}`,
{ method: 'DELETE' }
)
}

View File

@@ -229,3 +229,69 @@ export interface ChatMessage {
questions?: SpecQuestion[]
isStreaming?: boolean
}
// ============================================================================
// Assistant Chat Types
// ============================================================================
export interface AssistantConversation {
id: number
project_name: string
title: string | null
created_at: string | null
updated_at: string | null
message_count: number
}
export interface AssistantMessage {
id: number
role: 'user' | 'assistant' | 'system'
content: string
timestamp: string | null
}
export interface AssistantConversationDetail {
id: number
project_name: string
title: string | null
created_at: string | null
updated_at: string | null
messages: AssistantMessage[]
}
export interface AssistantChatTextMessage {
type: 'text'
content: string
}
export interface AssistantChatToolCallMessage {
type: 'tool_call'
tool: string
input: Record<string, unknown>
}
export interface AssistantChatResponseDoneMessage {
type: 'response_done'
}
export interface AssistantChatErrorMessage {
type: 'error'
content: string
}
export interface AssistantChatConversationCreatedMessage {
type: 'conversation_created'
conversation_id: number
}
export interface AssistantChatPongMessage {
type: 'pong'
}
export type AssistantChatServerMessage =
| AssistantChatTextMessage
| AssistantChatToolCallMessage
| AssistantChatResponseDoneMessage
| AssistantChatErrorMessage
| AssistantChatConversationCreatedMessage
| AssistantChatPongMessage