Ryan Malloy
44ed9936b7
Add comprehensive development intelligence system that tracks: - Development sessions with automatic start/stop - Full conversation history with semantic search - Tool usage and file operation analytics - Think time and engagement analysis - Git activity correlation - Learning pattern recognition - Productivity insights and metrics Features: - FastAPI backend with SQLite database - Modern web dashboard with interactive charts - Claude Code hook integration for automatic tracking - Comprehensive test suite with 100+ tests - Complete API documentation (OpenAPI/Swagger) - Privacy-first design with local data storage 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
530 lines
12 KiB
YAML
530 lines
12 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Claude Code Project Tracker API
|
|
description: |
|
|
REST API for tracking Claude Code development sessions, conversations, and productivity metrics.
|
|
|
|
This API is designed to be called by Claude Code hooks to automatically capture development workflow data.
|
|
version: 1.0.0
|
|
license:
|
|
name: MIT
|
|
|
|
servers:
|
|
- url: http://localhost:8000
|
|
description: Local development server
|
|
|
|
paths:
|
|
# Session Management
|
|
/api/session/start:
|
|
post:
|
|
summary: Start a new development session
|
|
description: Called by SessionStart hook to initialize project tracking
|
|
tags:
|
|
- Sessions
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SessionStart'
|
|
responses:
|
|
'201':
|
|
description: Session created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SessionResponse'
|
|
'400':
|
|
description: Invalid request data
|
|
|
|
/api/session/end:
|
|
post:
|
|
summary: End current development session
|
|
description: Called by Stop hook to finalize session tracking
|
|
tags:
|
|
- Sessions
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SessionEnd'
|
|
responses:
|
|
'200':
|
|
description: Session ended successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SessionResponse'
|
|
|
|
# Conversation Tracking
|
|
/api/conversation:
|
|
post:
|
|
summary: Log conversation exchange
|
|
description: Called by UserPromptSubmit and Stop hooks to capture dialogue
|
|
tags:
|
|
- Conversations
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ConversationEntry'
|
|
responses:
|
|
'201':
|
|
description: Conversation logged successfully
|
|
|
|
# Activity Tracking
|
|
/api/activity:
|
|
post:
|
|
summary: Record development activity
|
|
description: Called by PostToolUse hooks to track tool usage and file operations
|
|
tags:
|
|
- Activities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Activity'
|
|
responses:
|
|
'201':
|
|
description: Activity recorded successfully
|
|
|
|
# Waiting Period Tracking
|
|
/api/waiting/start:
|
|
post:
|
|
summary: Start waiting period
|
|
description: Called by Notification hook when Claude is waiting for input
|
|
tags:
|
|
- Waiting
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WaitingStart'
|
|
responses:
|
|
'201':
|
|
description: Waiting period started
|
|
|
|
/api/waiting/end:
|
|
post:
|
|
summary: End waiting period
|
|
description: Called when user submits new input
|
|
tags:
|
|
- Waiting
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WaitingEnd'
|
|
responses:
|
|
'200':
|
|
description: Waiting period ended
|
|
|
|
# Git Operations
|
|
/api/git:
|
|
post:
|
|
summary: Record git operation
|
|
description: Track git commands and repository state changes
|
|
tags:
|
|
- Git
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GitOperation'
|
|
responses:
|
|
'201':
|
|
description: Git operation recorded
|
|
|
|
# Data Retrieval
|
|
/api/projects:
|
|
get:
|
|
summary: List all tracked projects
|
|
description: Get overview of all projects with summary statistics
|
|
tags:
|
|
- Projects
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 50
|
|
- name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
responses:
|
|
'200':
|
|
description: List of projects
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ProjectSummary'
|
|
|
|
/api/projects/{project_id}/timeline:
|
|
get:
|
|
summary: Get detailed project timeline
|
|
description: Retrieve chronological history of project development
|
|
tags:
|
|
- Projects
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
responses:
|
|
'200':
|
|
description: Project timeline
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProjectTimeline'
|
|
|
|
# Analytics
|
|
/api/analytics/productivity:
|
|
get:
|
|
summary: Get productivity analytics
|
|
description: Retrieve engagement metrics and output analysis
|
|
tags:
|
|
- Analytics
|
|
parameters:
|
|
- name: project_id
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
- name: days
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 30
|
|
responses:
|
|
'200':
|
|
description: Productivity metrics
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProductivityMetrics'
|
|
|
|
/api/conversations/search:
|
|
get:
|
|
summary: Search conversations
|
|
description: Semantic search through conversation history
|
|
tags:
|
|
- Conversations
|
|
parameters:
|
|
- name: query
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: project_id
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 20
|
|
responses:
|
|
'200':
|
|
description: Search results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ConversationSearchResult'
|
|
|
|
components:
|
|
schemas:
|
|
# Session Schemas
|
|
SessionStart:
|
|
type: object
|
|
required:
|
|
- session_type
|
|
- working_directory
|
|
properties:
|
|
session_type:
|
|
type: string
|
|
enum: [startup, resume, clear]
|
|
working_directory:
|
|
type: string
|
|
git_branch:
|
|
type: string
|
|
git_repo:
|
|
type: string
|
|
environment:
|
|
type: object
|
|
|
|
SessionEnd:
|
|
type: object
|
|
required:
|
|
- session_id
|
|
properties:
|
|
session_id:
|
|
type: integer
|
|
end_reason:
|
|
type: string
|
|
enum: [normal, interrupted, timeout]
|
|
|
|
SessionResponse:
|
|
type: object
|
|
properties:
|
|
session_id:
|
|
type: integer
|
|
project_id:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
|
|
# Conversation Schemas
|
|
ConversationEntry:
|
|
type: object
|
|
required:
|
|
- session_id
|
|
- timestamp
|
|
properties:
|
|
session_id:
|
|
type: integer
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
user_prompt:
|
|
type: string
|
|
claude_response:
|
|
type: string
|
|
tools_used:
|
|
type: array
|
|
items:
|
|
type: string
|
|
files_affected:
|
|
type: array
|
|
items:
|
|
type: string
|
|
context:
|
|
type: object
|
|
|
|
# Activity Schemas
|
|
Activity:
|
|
type: object
|
|
required:
|
|
- session_id
|
|
- tool_name
|
|
- timestamp
|
|
properties:
|
|
session_id:
|
|
type: integer
|
|
tool_name:
|
|
type: string
|
|
enum: [Edit, Write, Read, Bash, Grep, Glob, Task, WebFetch]
|
|
action:
|
|
type: string
|
|
file_path:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
metadata:
|
|
type: object
|
|
success:
|
|
type: boolean
|
|
error_message:
|
|
type: string
|
|
|
|
# Waiting Period Schemas
|
|
WaitingStart:
|
|
type: object
|
|
required:
|
|
- session_id
|
|
- timestamp
|
|
properties:
|
|
session_id:
|
|
type: integer
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
context_before:
|
|
type: string
|
|
|
|
WaitingEnd:
|
|
type: object
|
|
required:
|
|
- session_id
|
|
- timestamp
|
|
properties:
|
|
session_id:
|
|
type: integer
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
duration_seconds:
|
|
type: number
|
|
context_after:
|
|
type: string
|
|
|
|
# Git Schemas
|
|
GitOperation:
|
|
type: object
|
|
required:
|
|
- session_id
|
|
- operation
|
|
- timestamp
|
|
properties:
|
|
session_id:
|
|
type: integer
|
|
operation:
|
|
type: string
|
|
enum: [commit, push, pull, branch, merge, rebase, status]
|
|
command:
|
|
type: string
|
|
result:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
files_changed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
lines_added:
|
|
type: integer
|
|
lines_removed:
|
|
type: integer
|
|
|
|
# Response Schemas
|
|
ProjectSummary:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
path:
|
|
type: string
|
|
git_repo:
|
|
type: string
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: string
|
|
total_sessions:
|
|
type: integer
|
|
total_time_minutes:
|
|
type: integer
|
|
last_activity:
|
|
type: string
|
|
format: date-time
|
|
files_modified:
|
|
type: integer
|
|
lines_changed:
|
|
type: integer
|
|
|
|
ProjectTimeline:
|
|
type: object
|
|
properties:
|
|
project:
|
|
$ref: '#/components/schemas/ProjectSummary'
|
|
timeline:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
type:
|
|
type: string
|
|
enum: [session_start, session_end, conversation, activity, git_operation]
|
|
data:
|
|
type: object
|
|
|
|
ProductivityMetrics:
|
|
type: object
|
|
properties:
|
|
engagement_score:
|
|
type: number
|
|
description: Overall engagement level (0-100)
|
|
average_session_length:
|
|
type: number
|
|
description: Minutes per session
|
|
think_time_average:
|
|
type: number
|
|
description: Average waiting time between interactions
|
|
files_per_session:
|
|
type: number
|
|
tools_most_used:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
tool:
|
|
type: string
|
|
count:
|
|
type: integer
|
|
productivity_trends:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
date:
|
|
type: string
|
|
format: date
|
|
score:
|
|
type: number
|
|
|
|
ConversationSearchResult:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
project_name:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
user_prompt:
|
|
type: string
|
|
claude_response:
|
|
type: string
|
|
relevance_score:
|
|
type: number
|
|
context:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
tags:
|
|
- name: Sessions
|
|
description: Development session management
|
|
- name: Conversations
|
|
description: Dialogue tracking and search
|
|
- name: Activities
|
|
description: Tool usage and file operations
|
|
- name: Waiting
|
|
description: Think time and engagement tracking
|
|
- name: Git
|
|
description: Repository operations
|
|
- name: Projects
|
|
description: Project data retrieval
|
|
- name: Analytics
|
|
description: Insights and metrics |