From 2b707aa890284f17870b174ba0b966d055a7c968 Mon Sep 17 00:00:00 2001
From: will-osborne <will.osborne@fourthfloorcreative.co>
Date: Thu, 23 Oct 2025 11:07:56 +0100
Subject: [PATCH 1/2] feat: add support for global custom instructions

---
 README.md                        | 38 ++++++++++++++++++++++++++++----
 src/utils/custom-instructions.ts | 24 ++++++++++++++------
 2 files changed, 51 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 60f9d623..3dcfc25a 100644
--- a/README.md
+++ b/README.md
@@ -296,15 +296,19 @@ Options:
 
 ### Custom Instructions
 
-You can provide custom instructions to tailor Grok's behavior to your project by creating a `.grok/GROK.md` file in your project directory:
+You can provide custom instructions to tailor Grok's behavior to your project or globally. Grok CLI supports both project-level and global custom instructions.
+
+#### Project-Level Instructions
+
+Create a `.grok/GROK.md` file in your project directory to provide instructions specific to that project:
 
 ```bash
 mkdir .grok
 ```
 
-Create `.grok/GROK.md` with your custom instructions:
+Create `.grok/GROK.md` with your project-specific instructions:
 ```markdown
-# Custom Instructions for Grok CLI
+# Custom Instructions for This Project
 
 Always use TypeScript for any new code files.
 When creating React components, use functional components with hooks.
@@ -313,7 +317,33 @@ Always add JSDoc comments for public functions and interfaces.
 Follow the existing code style and patterns in this project.
 ```
 
-Grok will automatically load and follow these instructions when working in your project directory. The custom instructions are added to Grok's system prompt and take priority over default behavior.
+#### Global Instructions
+
+For instructions that apply across all projects, create `~/.grok/GROK.md` in your home directory:
+
+```bash
+mkdir -p ~/.grok
+```
+
+Create `~/.grok/GROK.md` with your global instructions:
+```markdown
+# Global Custom Instructions for Grok CLI
+
+Always prioritize code readability and maintainability.
+Use descriptive variable names and add comments for complex logic.
+Follow best practices for the programming language being used.
+When suggesting code changes, consider performance implications.
+```
+
+#### Priority Order
+
+Grok will load custom instructions in the following priority order:
+1. **Project-level** (`.grok/GROK.md` in current directory) - takes highest priority
+2. **Global** (`~/.grok/GROK.md` in home directory) - fallback if no project instructions exist
+
+If both files exist, project instructions will be used. If neither exists, Grok operates with its default behavior.
+
+The custom instructions are added to Grok's system prompt and influence its responses across all interactions in the respective context.
 
 ## Morph Fast Apply (Optional)
 
diff --git a/src/utils/custom-instructions.ts b/src/utils/custom-instructions.ts
index f95f081c..98d6822b 100644
--- a/src/utils/custom-instructions.ts
+++ b/src/utils/custom-instructions.ts
@@ -1,18 +1,28 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 export function loadCustomInstructions(workingDirectory: string = process.cwd()): string | null {
   try {
-    const instructionsPath = path.join(workingDirectory, '.grok', 'GROK.md');
+    // First, try the working directory
+    let instructionsPath = path.join(workingDirectory, '.grok', 'GROK.md');
     
-    if (!fs.existsSync(instructionsPath)) {
-      return null;
+    if (fs.existsSync(instructionsPath)) {
+      const customInstructions = fs.readFileSync(instructionsPath, 'utf-8');
+      return customInstructions.trim();
     }
-
-    const customInstructions = fs.readFileSync(instructionsPath, 'utf-8');
-    return customInstructions.trim();
+    
+    // If not found, try the home directory
+    instructionsPath = path.join(os.homedir(), '.grok', 'GROK.md');
+    
+    if (fs.existsSync(instructionsPath)) {
+      const customInstructions = fs.readFileSync(instructionsPath, 'utf-8');
+      return customInstructions.trim();
+    }
+    
+    return null;
   } catch (error) {
     console.warn('Failed to load custom instructions:', error);
     return null;
   }
-}
\ No newline at end of file
+}

From 2610edb2bf0211ad73dfaaf1a769b386687af615 Mon Sep 17 00:00:00 2001
From: will-osborne <will.osborne@fourthfloorcreative.co>
Date: Thu, 23 Oct 2025 11:09:58 +0100
Subject: [PATCH 2/2] Remove comments

---
 src/utils/custom-instructions.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/utils/custom-instructions.ts b/src/utils/custom-instructions.ts
index 98d6822b..e9a87ce5 100644
--- a/src/utils/custom-instructions.ts
+++ b/src/utils/custom-instructions.ts
@@ -4,7 +4,6 @@ import * as os from 'os';
 
 export function loadCustomInstructions(workingDirectory: string = process.cwd()): string | null {
   try {
-    // First, try the working directory
     let instructionsPath = path.join(workingDirectory, '.grok', 'GROK.md');
     
     if (fs.existsSync(instructionsPath)) {
@@ -12,7 +11,6 @@ export function loadCustomInstructions(workingDirectory: string = process.cwd())
       return customInstructions.trim();
     }
     
-    // If not found, try the home directory
     instructionsPath = path.join(os.homedir(), '.grok', 'GROK.md');
     
     if (fs.existsSync(instructionsPath)) {