PROJECT OVERVIEW:
The application, tentatively named 'Claude Folder Manager & Optimizer', is a SaaS platform designed to empower software development teams and individual developers by providing a centralized, user-friendly interface for managing and optimizing the configuration files within the `.claude/` folder (and similar AI assistant configuration directories) in their projects. The core problem it solves is the lack of clarity and ease of use surrounding these configuration files, which are crucial for tailoring AI coding assistants like Claude Code to specific project needs. Many users treat these folders as black boxes, missing opportunities to leverage custom commands, agents, skills, and permissions effectively. This tool aims to demystify these configurations, enabling users to "configure Claude Code to behave exactly the way your team needs it to," thereby increasing the measurable ROI from AI tooling, as highlighted by the challenges in the Postman analysis.
VALUES PROPOSITION:
- **Clarity & Control:** Provides a visual, intuitive way to understand and manage AI assistant configurations.
- **Efficiency Boost:** Streamlines the creation, editing, and deployment of custom commands, agents, and skills.
- **Enhanced Collaboration:** Enables teams to standardize AI assistant behavior and share configurations.
- **Maximized ROI:** Helps users unlock the full potential of their AI coding tools, leading to tangible time and cost savings.
- **Simplified Setup:** Reduces the learning curve associated with complex configuration files.
TECH STACK:
- **Frontend Framework:** React.js (using Create React App for simplicity or Vite for speed, focusing on a single-page application experience).
- **Styling:** Tailwind CSS for rapid, utility-first UI development.
- **State Management:** Zustand or Jotai for lightweight and efficient global state management, suitable for a SPA.
- **Routing:** React Router DOM for client-side navigation.
- **API Communication:** Axios or native `fetch` API for interacting with a potential backend (for future features like team sync or cloud storage).
- **UI Components:** Headless UI or Radix UI for accessible, unstyled components that can be styled with Tailwind CSS. Libraries like `react-icons` for icons.
- **Code Editor Component:** Monaco Editor (the VS Code editor) or a simpler alternative like CodeMirror, embedded for editing command scripts and configuration files.
- **File System Interaction (Simulated/Local):** For MVP, we'll simulate file system interactions using local state and potentially `localStorage` or `IndexedDB`. A future version might explore Electron for desktop app capabilities to enable real file system access.
- **Build Tool:** Vite for fast development server and optimized builds.
CORE FEATURES & USER FLOW:
1. **Project Integration & Folder Scan:**
* **User Flow:** User initiates the process, potentially by pointing the application to a project root (simulated in MVP via upload or manual path entry). The app scans the specified directory (or simulates a scan based on mock data) and identifies the `.claude/` folder and its contents.
* **Details:** Visual representation of the folder structure within `.claude/`. Lists main configuration files (e.g., `CLAUDE.md`, `config.json`, custom command files, agent definitions).
2. **CLAUDE.md / Instructions Editor:**
* **User Flow:** User selects the `CLAUDE.md` or main instruction file. An integrated code editor (e.g., Monaco Editor) opens, allowing the user to view, edit, and save the content. Changes are reflected in the application's state and can be persisted locally.
* **Details:** Rich text editing capabilities or a Markdown editor with preview. Syntax highlighting if applicable. Save/discard changes functionality.
3. **Custom Commands Management:**
* **User Flow:** User navigates to the 'Custom Commands' section. They can view a list of existing commands (name, description, associated script/action). User can click 'Add New Command' to open a form for name, description, and the command's script (using the code editor). Edit/Delete options are available for existing commands.
* **Details:** Each command might have associated parameters or context. The script editor will support the relevant scripting language (e.g., shell scripts, Python snippets).
4. **Agents & Skills Configuration:**
* **User Flow:** User accesses the 'Agents & Skills' section. A list of defined agents is displayed. Selecting an agent shows its associated skills, instructions, and parameters. Users can add new agents, define their core function, and attach or create new skills (which might link back to the Custom Commands feature).
* **Details:** Structured form for agent properties (name, description, purpose). Linking mechanism for skills, potentially hierarchical.
5. **Permissions Management:**
* **User Flow:** User goes to 'Permissions'. A clear interface displays the access rules and granted permissions for Claude within the project (e.g., which directories it can read/write, what actions it can perform). Users can define new rules or modify existing ones through a form-based interface.
* **Details:** Rule builder with options like 'Allow/Deny', 'File/Directory Path', 'Action Type (read, write, execute)', 'Scope (specific files, patterns, all)'.
6. **Session Memory Viewer (Optional for MVP, focus on config):**
* **User Flow:** Access a read-only view of past interactions or memory states if the `.claude/` structure supports it directly.
* **Details:** Displaying conversation history snippets or key learned information. (Note: This might be complex depending on Claude's actual implementation and could be deferred).
UI/UX DESIGN:
- **Layout:** A clean, two-column layout. The left sidebar includes navigation for different sections (Dashboard/Overview, Instructions, Custom Commands, Agents & Skills, Permissions). The main content area displays the selected section's details.
- **Color Palette:** Primarily uses a dark theme suitable for developers (e.g., shades of dark gray, deep blues, with vibrant accent colors like electric blue or a bright teal for interactive elements and CTAs). White or light gray for text. Example: Background `#1a1a1a`, Sidebar `#222222`, Accent `#00bfff`, Text `#e0e0e0`.
- **Typography:** Modern, readable sans-serif fonts. Use a monospace font for code editor sections. Example: Main text `Inter` or `Roboto`, Code `Fira Code` or `Source Code Pro`.
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content areas reflow and stack vertically. Ensure usability on various screen sizes (desktops, tablets, mobiles).
- **Component Hierarchy:** A clear, nested structure. For example, `App` -> `Layout` -> `Sidebar`, `MainContent` -> `CommandList`, `CommandEditor`, etc.
- **Interactions:** Clear visual feedback on hover states for buttons and list items. Subtle transitions for panel openings/closings and route changes. Loading indicators (spinners, skeleton screens) for data fetching/processing.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing and global context.
- `Layout.jsx`: Contains the main structure (Sidebar + Main Content Area).
- `Sidebar.jsx`: Navigation menu component. Props: `activeItem`, `onItemClick`.
- `MainContent.jsx`: Dynamic area displaying content based on sidebar selection.
- `Dashboard.jsx`: Overview of the project's `.claude/` setup. Displays summary stats. Props: `projectConfigSummary`.
- `ConfigEditor.jsx`: Generic component for editing text-based configuration files (like `CLAUDE.md`). Uses Monaco Editor internally. Props: `initialContent`, `language`, `onChange`, `onSubmit`.
- `CommandList.jsx`: Displays a list of custom commands. Props: `commands`, `onEditCommand`, `onDeleteCommand`.
- `CommandForm.jsx`: Form for creating/editing a single custom command. Props: `commandData` (optional), `onSubmit`, `onCancel`.
- `AgentList.jsx`: Displays a list of AI agents. Props: `agents`, `onSelectAgent`.
- `AgentForm.jsx`: Form for configuring an agent. Props: `agentData` (optional), `onSubmit`, `onCancel`.
- `PermissionManager.jsx`: UI for managing permissions. Props: `permissions`, `onAddRule`, `onRemoveRule`.
- `RuleBuilder.jsx`: Component within `PermissionManager` to define a single permission rule. Props: `ruleData` (optional), `onSubmit`, `onCancel`.
- `CodeEditor.jsx`: Wrapper around Monaco Editor or similar. Props: `initialValue`, `language`, `onChange`.
- `Icon.jsx`: Reusable icon component.
- `Button.jsx`, `Input.jsx`, `Modal.jsx`, `LoadingSpinner.jsx`: Common UI utility components.
DATA MODEL:
- **State Structure (Zustand/Jotai):**
```javascript
// Example State Slice for Commands
{
commands: [
{
id: 'cmd-123',
name: 'refactor-code',
description: 'Refactors the selected code block.',
script: 'python refactor.py --selected', // Example script
createdAt: '2023-10-27T10:00:00Z',
updatedAt: '2023-10-27T10:05:00Z'
}
],
isLoadingCommands: false,
error: null
}
// Similar structures for agents, permissions, instructions (CLAUDE.md content)
```
- **Mock Data Formats:** JSON objects representing the structure of `.claude/` contents. For MVP, this will be hardcoded or loaded from local JSON files.
- **Persistence:** Use `localStorage` for MVP to store configurations locally per project instance opened in the app. For team features, a backend API would be needed.
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on buttons, list items, and navigation links.
- **Transitions:** Smooth `ease-out` transitions for opening/closing modals, expanding/collapsing sections, and route changes (e.g., fade-in/out).
- **Loading States:** Use `react-tsparticles` or a simple CSS spinner (`LoadingSpinner.jsx`) when fetching or saving data. Skeleton loaders can be used for list items while loading.
- **Micro-interactions:** Visual confirmation (e.g., a small checkmark animation) when a command is saved successfully. Subtle animations when adding/removing items from lists.
- **Code Editor:** Syntax highlighting, line numbers, basic autocompletion hints if possible.
EDGE CASES:
- **No `.claude/` folder found:** Display a clear message and potentially a button to help initialize or create a basic structure.
- **Empty State:** When no commands, agents, or permissions are configured, display helpful messages and clear calls to action (e.g., "Create your first custom command").
- **Error Handling:** Gracefully handle errors during file operations (simulated or real), API calls, or script execution. Display user-friendly error messages (e.g., "Failed to save command. Please check your script."). Use a global error boundary and display toasts/snackbars for errors.
- **Validation:** Validate input fields for command names, agent properties, and script syntax where applicable. Provide inline validation feedback.
- **Accessibility (a11y):** Use semantic HTML, ARIA attributes where necessary, ensure keyboard navigation, sufficient color contrast, and focus management, especially for modals and interactive elements.
- **Large Configurations:** Ensure the UI remains performant even with a large number of commands or complex agent definitions.
SAMPLE DATA:
1. **CLAUDE.md Content:**
```markdown
# Claude Code Configuration
This project uses Claude Code to assist with Python development.
**Primary Goal:** Maintain code quality and improve development speed.
**Key Instructions:**
- Always adhere to PEP 8 standards.
- Prefer functional programming paradigms where appropriate.
- Document all new functions and classes.
```
2. **Custom Command - Refactor:**
```json
{
"id": "cmd-refactor-001",
"name": "Refactor Code Block",
"description": "Refactors the currently selected code block using a predefined Python script.",
"script": "echo 'Simulating refactoring...' && python scripts/refactor_tool.py --selection",
"createdAt": "2024-03-15T11:30:00Z",
"updatedAt": "2024-03-15T11:35:00Z"
}
```
3. **Custom Command - Generate Docs:**
```json
{
"id": "cmd-gendocs-002",
"name": "Generate Docstrings",
"description": "Generates PEP 257 compliant docstrings for the selected Python function or class.",
"script": "claude.generate_docstrings --context=selection",
"createdAt": "2024-03-15T11:40:00Z",
"updatedAt": "2024-03-15T11:42:00Z"
}
```
4. **Agent - Code Reviewer:**
```json
{
"id": "agent-reviewer-001",
"name": "Automated Code Reviewer",
"description": "Performs automated checks for code quality, style, and potential bugs.",
"instructions": "Analyze the provided code for adherence to project standards (PEP 8, security best practices) and identify potential issues.",
"skills": ["cmd-refactor-001", "cmd-gendocs-002", "run-linter"],
"permissions": ["read:source", "report:issues"]
}
```
5. **Permission Rule:**
```json
{
"id": "perm-rule-003",
"type": "allow",
"action": "read",
"target": "src/**/*.py",
"description": "Allow reading all Python source files."
}
```
6. **Permission Rule (Deny):**
```json
{
"id": "perm-rule-004",
"type": "deny",
"action": "write",
"target": "config/secrets.json",
"description": "Deny writing to sensitive secrets file."
}
```
7. **Mock Project Structure:**
```
my-project/
├── .claude/
│ ├── CLAUDE.md
│ ├── commands/
│ │ ├── refactor.py
│ │ └── generate_docs.sh
│ ├── agents/
│ │ └── reviewer.json
│ ├── permissions.json
│ └── memory.db (Conceptual)
├── src/
│ └── main.py
└── README.md
```
DEPLOYMENT NOTES:
- **Build Command:** `npm run build` or `yarn build` (using Vite).
- **Environment Variables:** Use `.env` files for configuration (e.g., `VITE_API_URL` if a backend is introduced). For MVP, most config is local.
- **Static Hosting:** The built application can be hosted on static hosting platforms like Netlify, Vercel, GitHub Pages, or AWS S3.
- **Local Development:** Run `npm run dev` or `yarn dev` for the development server.
- **Simulated File Access:** For MVP, file system interactions are simulated. Users might 'upload' a mock `.claude/` folder structure or the app could generate mock data. `localStorage` or `IndexedDB` can be used for persistence within the browser session.
- **Future Extension (Desktop):** For direct file system access, consider packaging the app using Electron. This would require significant changes to handle Node.js file system APIs.
- **Performance:** Optimize bundle size using Vite's features. Code-split components where necessary. Lazy-load the Monaco Editor if it significantly impacts initial load time.