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