feat: add Coderrr Insights dashboard for productivity tracking and Skills for better workflow

README.md

@@ -38,6 +38,7 @@ Coderrr is an AI-powered coding agent that analyzes tasks, creates actionable pl
 - [Architecture](#architecture)
 - [Codebase Intelligence](#codebase-intelligence)
 - [Safety Features](#safety-features)
+- [Project Customization](#project-customization)
 - [Supported Test Frameworks](#supported-test-frameworks)
 - [Contributing](#contributing)
 - [Documentation](#documentation)
@@ -57,6 +58,7 @@ Coderrr is an AI-powered coding agent that analyzes tasks, creates actionable pl
 - **Task Analysis** - Breaks down complex requests into structured, actionable TODO items
 - **File Operations** - Create, update, patch, delete, and read files with automatic directory creation
 - **Command Execution** - Runs shell commands with mandatory permission prompts (GitHub Copilot-style)
+- **Separate Terminal Execution** - Long-running commands run in their own terminal window, keeping Coderrr responsive
 - **Self-Healing** - Automatically retries failed steps with AI-generated fixes
 - **Auto Testing** - Automatically detects and runs tests after completing tasks
 - **Codebase Intelligence** - Scans and understands project structure for accurate file editing
@@ -66,6 +68,9 @@ Coderrr is an AI-powered coding agent that analyzes tasks, creates actionable pl
 
 ### Advanced Features
 
+- **Cross-Session Memory** - Remembers conversation context across sessions via `.coderrr/memory.json`
+- **Skills.md Support** - Define persistent coding guidelines and patterns for your project
+- **Coderrr.md Support** - Add task-specific instructions that guide AI behavior
 - **Codebase Scanner** - Automatic project awareness with 1-minute cache
 - **Multi-Framework Support** - Works with Node.js, Python, Go, Rust, Java projects
 - **Environment Configuration** - Flexible backend configuration via environment variables
@@ -245,7 +250,7 @@ coderrr start --dir /path/to/project
 3. **TODO Generation** - Tasks are broken down into actionable steps
 4. **Execution** - The agent executes each step:
    - File operations (create, update, patch, delete)
-   - Command execution (with permission prompts)
+   - Command execution in separate terminal windows (with permission prompts)
 5. **Testing** - Automatically runs tests if a test framework is detected
 6. **Completion** - Shows summary and execution statistics
 ---
@@ -332,6 +337,53 @@ This means when you ask to "edit the agent file", it knows you mean `src/agent.j
 
 ---
 
+## Project Customization
+
+Coderrr supports project-specific customization through special files:
+
+### Skills.md - Persistent Guidelines
+
+Create a `Skills.md` file in your project root to define coding guidelines that apply to **all tasks**:
+
+```markdown
+# Project Skills
+
+## Code Style
+- Use TypeScript strict mode
+- Prefer functional components in React
+- Always add JSDoc comments to public functions
+
+## Architecture
+- Follow clean architecture patterns
+- Keep business logic in /src/domain
+```
+
+### Coderrr.md - Task-Specific Instructions
+
+Create a `Coderrr.md` file for task-specific guidance:
+
+```markdown
+# Current Focus
+
+Working on authentication module. Priority:
+1. Security first - validate all inputs
+2. Use bcrypt for password hashing
+3. JWT tokens with 1-hour expiry
+```
+
+### Cross-Session Memory
+
+Coderrr automatically saves conversation history in `.coderrr/memory.json`:
+
+- **Persists across sessions** - Resume where you left off
+- **Project-specific** - Each project has its own memory
+- **Auto-managed** - Keeps last 30 conversation turns
+- **Clear anytime** - Delete `.coderrr/memory.json` to reset
+
+> **Tip:** Add `.coderrr/` to your `.gitignore` to keep conversation history private.
+
+---
+
 ## Supported Test Frameworks
 
 Coderrr automatically detects and runs tests for:

backend/main.py

@@ -163,6 +163,54 @@ class HealthResponse(BaseModel):
 
 ---
 
+## PROTECTED FILES - NEVER DELETE THESE:
+The following files are configuration files and MUST NOT be deleted:
+- Coderrr.md (user's custom instructions)
+- Skills.md (user's skills configuration)
+- .coderrr/ (configuration directory)
+
+If the user asks to "delete everything" or "clear the directory", SKIP these protected files.
+
+---
+
+## PATCH_FILE RULES - CRITICAL:
+The `patch_file` action replaces EXACT text matches. Follow these rules:
+
+1. **ALWAYS read the file first** before using patch_file
+2. The `oldContent` MUST be an EXACT copy from the file (not a placeholder)
+3. NEVER use placeholders like "<!-- existing content -->" or regex patterns
+4. If you haven't read the file, use `read_file` first, then patch in a follow-up
+
+### WRONG (will fail):
+```json
+{"action": "patch_file", "oldContent": "<!-- hero section -->", "newContent": "..."}
+```
+
+### CORRECT:
+```json
+{"action": "read_file", "path": "index.html", "summary": "Read file to get exact content"}
+```
+Then after seeing the content, use the EXACT text for oldContent.
+
+---
+
+## CHOOSING BETWEEN UPDATE_FILE AND PATCH_FILE:
+
+- **update_file**: Replaces the ENTIRE file. Use when:
+  - Creating new content from scratch
+  - Major rewrites (>50% of file changing)
+  - File structure is completely changing
+
+- **patch_file**: Replaces only a PORTION. Use when:
+  - Adding a new section to existing file
+  - Modifying a specific function or component
+  - User says "add", "modify", "enhance", "update" a specific part
+  - PRESERVING existing code is important
+
+**CRITICAL**: When user asks to "add animations" or "enhance the hero section", use patch_file to PRESERVE existing styles and features. Do NOT use update_file which would erase everything else.
+
+---
+
 The JSON MUST follow this exact schema:
 {
   "explanation": "Your answer or explanation of what you will do",
@@ -171,18 +219,20 @@ class HealthResponse(BaseModel):
       "action": "ACTION_TYPE",
       "path": "file/path if applicable",
       "content": "file content if creating/updating files",
+      "oldContent": "exact text to find (for patch_file only)",
+      "newContent": "replacement text (for patch_file only)",
       "command": "shell command if action is run_command",
       "summary": "Brief description of this step"
     }
   ]
 }
 
 Valid ACTION_TYPE values:
-- "read_file": Read and examine a file (requires path, summary) - USE FOR QUESTIONS
+- "read_file": Read and examine a file (requires path, summary) - USE FOR QUESTIONS OR BEFORE PATCHING
 - "create_file": Create a new file (requires path, content, summary)
-- "update_file": Replace entire file content (requires path, content, summary)
-- "patch_file": Modify part of a file (requires path, oldContent, newContent, summary)
-- "delete_file": Delete a file (requires path, summary)
+- "update_file": Replace ENTIRE file content (requires path, content, summary) - use sparingly!
+- "patch_file": Modify PART of a file (requires path, oldContent, newContent, summary) - preferred for edits
+- "delete_file": Delete a file (requires path, summary) - NEVER delete protected files
 - "run_command": Execute a shell command (requires command, summary)
 - "create_dir": Create a directory (requires path, summary)
 
@@ -193,6 +243,9 @@ class HealthResponse(BaseModel):
 4. Each plan item MUST have "action" and "summary" fields
 5. For run_command, use PowerShell syntax on Windows
 6. DO NOT create files when user is asking ABOUT existing files - read them instead!
+7. NEVER delete Coderrr.md, Skills.md, or .coderrr directory
+8. ALWAYS read a file before using patch_file on it
+9. When enhancing/adding features, use patch_file to preserve existing code
 """
 
 

bin/coderrr.js

@@ -16,6 +16,14 @@ const configManager = require('../src/configManager');
 const { getProviderChoices, getModelChoices, getProvider, validateApiKey } = require('../src/providers');
 const { tryExtractJSON } = require('../src/utils');
 
+const { displayInsights } = require('../src/insightsUI');
+
+program
+  .command('insights')
+  .description('Display local usage statistics and task history')
+  .action(() => {
+    displayInsights();
+  });
 // Optional: Load .env from user's home directory (for advanced users who want custom backend)
 const homeConfigPath = path.join(os.homedir(), '.coderrr', '.env');
 if (fs.existsSync(homeConfigPath)) {

docs/insights-guide.md

@@ -0,0 +1,14 @@
+# 📊 Coderrr Insights Guide
+
+Coderrr Insights is a local analytics module that tracks your AI-powered coding activity. It helps you visualize the impact of the agent on your workflow.
+
+## Features
+- **Usage Statistics:** Track total tasks, file modifications, and self-healing successes.
+- **Productivity Estimation:** See how much manual coding time you've potentially saved.
+- **Local History:** View a snapshot of your last 50 coding sessions.
+
+## How to View Insights
+To open your dashboard, simply run the following command in your terminal:
+
+```bash
+coderrr insights