feat: add knowledge files support for additional project context #48

connor-tyndall · 2026-01-12T00:24:49Z

Summary

This PR adds the ability to upload markdown files to provide additional context to the agent during development sessions, addressing issue #22.

Changes

Backend (API):

Added knowledge file CRUD endpoints to server/routers/projects.py:
- GET /{name}/knowledge - List all knowledge files
- GET /{name}/knowledge/{filename} - Get file content
- POST /{name}/knowledge - Upload a new markdown file
- DELETE /{name}/knowledge/{filename} - Delete a file
Added Pydantic schemas for knowledge file operations in server/schemas.py
Files are stored in each project's knowledge/ directory
Path traversal protection on filename validation

Prompt Updates:

Updated coding_prompt.template.md to instruct the agent to read knowledge files at the start of each session
Updated initializer_prompt.template.md to read knowledge files before creating features

Usage

Users can upload markdown files (requirements docs, design specs, research notes, etc.) via the API. The agent will automatically read these files at the start of each session to better understand the project context.

Note

The UI component for uploading/managing knowledge files would be a separate enhancement - this PR adds the backend infrastructure and prompt integration.

Closes #22

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Knowledge Files management system for storing and organizing project documentation
- Knowledge Files modal enabling list, view, edit, create, and delete operations
- Keyboard shortcut (K) to quickly access Knowledge Files
- Integration of knowledge content into AI initialization workflow for improved context

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add ability to upload markdown files to provide additional context to the agent during development sessions. Backend changes: - Add API endpoints for knowledge file CRUD (list, get, upload, delete) - Add Pydantic schemas for knowledge file operations - Files stored in project's knowledge/ directory Prompt changes: - Update coding prompt to read knowledge files at session start - Update initializer prompt to read knowledge files before creating features Closes leonvanzyl#22 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add a React component for managing knowledge files in the UI: - KnowledgeFilesModal with full CRUD operations (create, view, edit, delete) - API client functions for knowledge file endpoints - React Query hooks for data fetching and mutations - Keyboard shortcut 'K' to open knowledge files - BookOpen icon button in header when project is selected Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

coderabbitai · 2026-01-12T00:31:18Z

📝 Walkthrough

Walkthrough

This PR implements a knowledge file management system for projects, enabling users to upload, view, edit, list, and delete markdown files within each project's knowledge directory. The feature includes backend endpoints, API layer, React Query hooks, and a full-featured modal UI with keyboard shortcuts.

Changes

Cohort / File(s)	Summary
Prompt Templates `.claude/templates/coding_prompt.template.md`, `.claude/templates/initializer_prompt.template.md`	Adds knowledge directory discovery steps and instructions to read all `.md` files from the knowledge/ directory; updates step numbering to accommodate new workflow.
Backend Schemas `server/schemas.py`	Introduces four new models: `KnowledgeFile`, `KnowledgeFileList`, `KnowledgeFileContent`, `KnowledgeFileUpload` with filename validation for markdown files.
Backend Endpoints `server/routers/projects.py`	Adds five new knowledge management endpoints: list, get, upload, and delete knowledge files; includes helper function for knowledge directory path resolution and validation for project names, file existence, and filename security (path traversal prevention).
Frontend Types & API `ui/src/lib/types.ts`, `ui/src/lib/api.ts`	Introduces `KnowledgeFile`, `KnowledgeFileList`, `KnowledgeFileContent` types and four new API functions (`listKnowledgeFiles`, `getKnowledgeFile`, `uploadKnowledgeFile`, `deleteKnowledgeFile`) for knowledge file operations.
Frontend Hooks `ui/src/hooks/useProjects.ts`	Adds four new React Query hooks (`useKnowledgeFiles`, `useKnowledgeFile`, `useUploadKnowledgeFile`, `useDeleteKnowledgeFile`) for knowledge file data fetching and mutations.
Frontend Modal Component `ui/src/components/KnowledgeFilesModal.tsx`	New 455-line component providing full-featured modal UI with list, view, edit, and create modes; includes delete confirmation, file size/date formatting, error handling, keyboard accessibility, and automatic `.md` extension handling.
Frontend App Integration `ui/src/App.tsx`	Integrates knowledge files feature with new modal state, BookOpen icon button in header, keyboard shortcuts (K to open), Escape handling, and query invalidation for feature sync.

Sequence Diagrams

sequenceDiagram
    actor User
    participant App as App.tsx
    participant Modal as KnowledgeFilesModal
    participant Hooks as React Query Hooks
    participant API as API Layer
    participant Server as Backend Server
    participant FS as File System

    User->>App: Click Knowledge Files Button (or press K)
    App->>Modal: Show Modal
    Modal->>Hooks: useKnowledgeFiles(projectName)
    Hooks->>API: listKnowledgeFiles()
    API->>Server: GET /projects/{name}/knowledge
    Server->>FS: Read knowledge/ directory
    FS-->>Server: File list with metadata
    Server-->>API: KnowledgeFileList
    API-->>Hooks: Return file list
    Hooks-->>Modal: Display files
    
    User->>Modal: Click Edit on File
    Modal->>Hooks: useKnowledgeFile(projectName, filename)
    Hooks->>API: getKnowledgeFile()
    API->>Server: GET /projects/{name}/knowledge/{filename}
    Server->>FS: Read file content
    FS-->>Server: File content
    Server-->>API: KnowledgeFileContent
    API-->>Hooks: Return content
    Hooks-->>Modal: Load into editor
    
    User->>Modal: Save Changes
    Modal->>Hooks: useUploadKnowledgeFile()
    Hooks->>API: uploadKnowledgeFile()
    API->>Server: POST /projects/{name}/knowledge
    Server->>FS: Write file
    FS-->>Server: Success
    Server-->>API: Updated file
    API-->>Hooks: Confirm
    Hooks-->>Modal: Refresh list

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A clever warren builds its knowledge store,
With markdown files unlocked and more,
Upload, edit, view, delete with ease—
Your project's wisdom flows like breeze! 📚✨
Knowledge shared among your agent friends,
Where understanding never ends! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 29.41% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add knowledge files support for additional project context' accurately and clearly summarizes the main change—introducing markdown knowledge file support for projects.
Linked Issues check	✅ Passed	The PR fully implements the core requirement from #22: backend endpoints for uploading, listing, reading, and deleting markdown files; storage in project knowledge/ directories; prompt integration for agent consumption; and a complete UI component for file management.
Out of Scope Changes check	✅ Passed	Minor style/formatting changes (quote consistency, semicolons) in multiple files are incidental and consistent with code quality improvements; all substantive changes directly support knowledge file functionality.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In @server/routers/projects.py:
- Around line 389-398: The import "from datetime import datetime" is inside the
loop that builds files from knowledge_dir.glob("*.md"), causing repeated import
overhead; move that import out of the loop (preferably to the module top with
other imports) and remove the in-loop import statement so the loop that appends
KnowledgeFile(name=filepath.name, size=stat.st_size,
modified=datetime.fromtimestamp(stat.st_mtime)) uses the already-imported
datetime.

In @ui/src/components/KnowledgeFilesModal.tsx:
- Around line 439-454: The modal uses aria-labelledby="knowledge-files-title"
but no element has that id; update the heading rendered by renderList to include
id="knowledge-files-title" so the dialog label reference resolves, and consider
assigning dynamic ids for headings in renderView and renderEdit (e.g.,
knowledge-files-title--view and knowledge-files-title--edit) and using those ids
when viewMode === "view" or "edit" to keep the aria-labelledby reference
accurate across modes; locate renderList, renderView, renderEdit and the modal
container to add the ids and switch the aria-labelledby value accordingly if you
implement dynamic ids.

🧹 Nitpick comments (3)

ui/src/components/KnowledgeFilesModal.tsx (3)
54-59: Consider guarding against overwriting in-progress edits.

This effect syncs fileContent to editContent whenever fileContent changes in edit mode. If the backend data updates while a user is editing (e.g., from another tab), their local changes would be silently overwritten. Consider tracking whether the user has made local edits to prevent this.

61-82: Potential duplicate Escape key handling with parent component.

This component adds its own Escape handler while App.tsx also handles Escape. Since neither calls e.stopPropagation(), pressing Escape in view/edit mode navigates back to list here, but may also trigger the parent's handler. Consider calling e.stopPropagation() after handling the key to prevent the event from propagating.
♻️ Suggested fix
     const handleEscape = (e: KeyboardEvent) => {
       if (e.key === "Escape") {
+        e.stopPropagation();
         if (deleteConfirm) {
           setDeleteConfirm(null);
         } else if (viewMode !== "list") {
           setViewMode("list");
           setSelectedFile(null);
           setNewFileName("");
           setEditContent("");
         } else {
           onClose();
         }
       }
     };
231-253: Action buttons are hidden from keyboard users.

The file action buttons (View, Edit, Delete) use opacity-0 group-hover:opacity-100, making them invisible to keyboard-only users who can't trigger hover states. Consider keeping them visible but perhaps more subtle, or making them visible on focus-within.
♻️ Suggested fix
-                  <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+                  <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 transition-opacity">

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b1473cd and c7e7978.

📒 Files selected for processing (9)

.claude/templates/coding_prompt.template.md
.claude/templates/initializer_prompt.template.md
server/routers/projects.py
server/schemas.py
ui/src/App.tsx
ui/src/components/KnowledgeFilesModal.tsx
ui/src/hooks/useProjects.ts
ui/src/lib/api.ts
ui/src/lib/types.ts

🧰 Additional context used

📓 Path-based instructions (4)

ui/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

ui/src/**/*.{ts,tsx}: Use TypeScript for React components in the UI (React 18 with TypeScript)
Use React Query (TanStack Query) for API calls and data fetching in the UI
Use Radix UI for component primitives in the React UI
Run ESLint to lint React UI code

Files:

ui/src/components/KnowledgeFilesModal.tsx
ui/src/App.tsx
ui/src/hooks/useProjects.ts
ui/src/lib/api.ts
ui/src/lib/types.ts

**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Use SQLite with SQLAlchemy ORM for database access and feature management

Files:

server/schemas.py
server/routers/projects.py

.claude/templates/**/*.template.md

📄 CodeRabbit inference engine (CLAUDE.md)

Prompt templates should follow a fallback chain: project-specific in {project_dir}/prompts/{name}.md, then base template in .claude/templates/{name}.template.md

Files:

.claude/templates/initializer_prompt.template.md
.claude/templates/coding_prompt.template.md

server/routers/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Use FastAPI for REST API endpoints in the server/routers/ directory

Files:

server/routers/projects.py

🧠 Learnings (5)