 Courses from John Lindquist

Finding the *perfect* code editor theme is a myth.  There are always small visual tweaks you'd like to make, but forking and maintaining an entire theme is overkill.  This lesson shows you how to quickly and easily customize *any* theme directly within Cursor (or VS Code) using the `workbench.colorCustomizations` setting in your `settings.json` file.

**The Problem:**

*   No single theme perfectly matches everyone's preferences.
*   Minor visual annoyances (like search highlight colors) can impact focus and productivity.
*   Forking and publishing a theme for small changes is excessive.

**The Solution: `workbench.colorCustomizations`**

This setting allows you to override specific color values of your current theme *without* creating a new theme.  You get fine-grained control over the editor's appearance.

**How it Works:**

1.  **Open Settings (JSON):** Use the command palette (`Cmd/Ctrl + Shift + P`) and search for "Preferences: Open User Settings (JSON)". It is best to create a new editor group to the right, and then open the json settings, so that you can visualize your changes.
2.  **Add `workbench.colorCustomizations`:**  Within your `settings.json`, add a `"workbench.colorCustomizations"` object.
3.  **Use Autocomplete:** Inside this object, start typing "editor." and use Cursor's/VS Code's autocomplete to explore the available customization options.  Examples include:
    *   `editor.findMatchBackground`: Background color of search matches.
    *   `editor.findMatchHighlightBackground`: Background color of the *current* search match.
    *   `editor.findMatchBorder`: Border color of search matches.
    *   `editor.findMatchHighlightBorder`: Border color of the *current* search match.
    *   `editor.background`: Overall editor background color.
    *   ...and many more!
4.  **Set Color Values:** Assign valid color values (hex codes, named colors, etc.) to the properties you want to change.  You can even use transparency (alpha channel) with hex codes (e.g., `#FF000022` for a semi-transparent red).
5.  **Save and See the Changes:**  As soon as you save `settings.json`, the changes are applied *live* to your editor.  Experiment with different colors until you find what works best.

**Benefits:**

*   **Precise Control:**  Tweak individual elements of your theme without affecting others.
*   **No Forking Needed:**  Make personal adjustments without the overhead of creating and managing a separate theme.
*   **Live Updates:**  See your changes instantly as you edit the JSON.
*   **Easy Experimentation:**  Try out different colors and settings quickly.

This lesson demonstrates a simple yet powerful way to personalize your coding environment, improving focus and making your editor truly your own. No need for extensive theme development – just targeted tweaks to make things *just right*.


John Lindquist

Personalize Your Cursor/VS Code Theme with workbench.colorCustomizations

AI coding assistants (like Cursor's Composer) are powerful, but running a single instance can become a bottleneck, especially for larger tasks or when experimenting with different approaches.  This lesson shows you how to break free from that limitation by leveraging Git worktrees to enable *parallel* AI development.

**The Problem:**

*   Single Composer instances can be slow for complex tasks.
*   Multiple agents modifying the same files simultaneously lead to conflicts.
*   Traditional branching can be cumbersome for rapid experimentation.

**The Solution: Git Worktrees**

Git worktrees allow you to create multiple, *independent* working directories linked to the *same* Git repository. Each worktree can be associated with a different branch, providing isolated environments for development.

**Workflow:**

1.  **Create Worktrees:** Use `git worktree add -b <branch-name> ../<project-name>-<branch-name>` to create a new worktree and associated branch.  The `-b` flag creates the branch. The path (`../<project-name>-<branch-name>`) places the worktree in a sibling directory (cleaner organization). Repeat for each variation you want to explore.
2.  **Launch Multiple Cursor Instances:** Open Cursor in each worktree directory (e.g., `cursor ../my-project-variant1`). Each instance is now isolated and can work on its assigned branch.
3.  **Assign Tasks to Composer:**  Within each Cursor instance, use Composer (Chat or Agent mode) to work on specific tasks or implement different approaches to the same problem. Use `@` to provide context (files, directories, docs).
4.  **Monitor and Iterate:** Check in on each Composer instance's progress. Because they're in separate worktrees, there are no conflicts.
5.  **Merge the Best Solution:**  Once a branch has a successful solution, merge it back into your main branch using `git merge <branch-name>`.
6.  **Clean Up:** Remove the worktrees with `git worktree remove ../<project-name>-<branch-name>`.

**ZSH Functions (Optional but Powerful):**

The lesson introduces two ZSH functions (provided as code snippets) to automate this process:

*   `wtree()`:  Takes branch names as arguments, creates corresponding worktrees, installs dependencies (with `-p` flag for PNPM), and optionally launches Cursor in each.  This streamlines setup.
*   `wtmerge()`:  Takes a single branch name as an argument, merges that branch into `main`, and then *cleans up all* worktrees created by `wtree()`. This simplifies merging and cleanup.

**Benefits:**

*   **Parallel Development:**  Run multiple Composer instances simultaneously, drastically speeding up development.
*   **Conflict-Free Experimentation:**  Isolate different approaches in separate branches/worktrees, eliminating merge conflicts.
*   **Rapid Iteration:**  Quickly create, test, and merge (or discard) variations of your code.
*   **Clean Workspace:**  Worktrees keep your main project directory uncluttered.

This lesson empowers you to unlock the full potential of AI coding assistants by running them in parallel, fostering faster experimentation and more efficient development. You'll learn a practical technique that significantly boosts your productivity when working with AI-generated code.

```bash
# wtree: Create a new worktree for each given branch.
# Usage: wtree [ -p|--pnpm ] branch1 branch2 ...
#
# This function does the following:
#   1. Parses command-line arguments; if -p/--pnpm is provided, it will later run "pnpm install".
#   2. Determines the current branch and repository root.
#   3. Uses a fixed parent directory (~/dev) to house all worktree directories.
#   4. For each branch passed:
#        - If the branch does not exist, it is created from the current branch.
#        - It checks that a worktree for that branch does not already exist.
#        - It then creates a worktree in ~/dev using a naming convention: <repoName>-<branch>.
#        - If the install-deps flag is true, it runs "pnpm install" inside the new worktree.
#        - Finally, it either opens the new worktree via the custom "cursor" command (if defined)
#          or prints its path.
wtree() {
  # Flag to determine whether to run "pnpm install"
  local install_deps=false
  local branches=()

  # Parse command-line arguments
  while [[ $# -gt 0 ]]; do
    case "$1" in
      -p|--pnpm)
        install_deps=true
        shift
        ;;
      *)
        branches+=("$1")
        shift
        ;;
    esac
  done

  # Ensure at least one branch name is provided.
  if [[ ${#branches[@]} -eq 0 ]]; then
    echo "Usage: wtree [ -p|--pnpm ] branch1 branch2 ..."
    return 1
  fi

  # Determine the current branch; exit if not in a git repository.
  local current_branch
  current_branch=$(git rev-parse --abbrev-ref HEAD) || {
    echo "Error: Not a git repository."
    return 1
  }

  # Determine repository root and name.
  local repo_root repo_name
  repo_root=$(git rev-parse --show-toplevel) || {
    echo "Error: Cannot determine repository root."
    return 1
  }
  repo_name=$(basename "$repo_root")

  # Set fixed parent directory for worktrees.
  local worktree_parent="$HOME/dev"
  # Ensure the worktree parent directory exists.
  if [[ ! -d "$worktree_parent" ]]; then
    if ! mkdir -p "$worktree_parent"; then
      echo "Error: Failed to create worktree parent directory: $worktree_parent"
      return 1
    fi
  fi

  # Loop over each branch provided as argument.
  for branch in "${branches[@]}"; do
    # Define the target path using a naming convention: <repoName>-<branch>
    local target_path="$worktree_parent/${repo_name}-${branch}"
    
    echo "Processing branch: ${branch}"

    # Check if a worktree already exists at the target path.
    if git worktree list | grep -q "^${target_path}[[:space:]]"; then
      echo "Error: Worktree already exists at ${target_path}. Skipping branch '${branch}'."
      continue
    fi

    # If the branch does not exist, create it from the current branch.
    if ! git show-ref --verify --quiet "refs/heads/${branch}"; then
      echo "Branch '${branch}' does not exist. Creating it from '${current_branch}'..."
      if ! git branch "${branch}"; then
        echo "Error: Failed to create branch '${branch}'. Skipping."
        continue
      fi
    fi

    # Create the new worktree for the branch.
    echo "Creating worktree for branch '${branch}' at ${target_path}..."
    if ! git worktree add "$target_path" "${branch}"; then
      echo "Error: Failed to create worktree for branch '${branch}'. Skipping."
      continue
    fi

    # If the install flag is set, run "pnpm install" in the new worktree.
    if $install_deps; then
      echo "Installing dependencies in worktree for branch '${branch}'..."
      if ! ( cd "$target_path" && pnpm install ); then
        echo "Warning: Failed to install dependencies in '${target_path}'."
      fi
    fi

    # Optionally, open the worktree directory via a custom "cursor" command if available.
    if type cursor >/dev/null 2>&1; then
      cursor "$target_path"
    else
      echo "Worktree created at: ${target_path}"
    fi

    echo "Worktree for branch '${branch}' created successfully."
    echo "-----------------------------------------------------"
  done
}


# wtmerge: Merge changes from a specified worktree branch into main,
# then clean up all worktrees and delete their branches.
#
# Usage: wtmerge <branch-to-keep>
#
# This function does the following:
#   1. Verifies that the branch to merge (branch-to-keep) exists as an active worktree.
#   2. Checks for uncommitted changes in that worktree:
#        - If changes exist, it attempts to stage and commit them.
#        - It gracefully handles the situation where there are no changes.
#   3. Switches the current (main) worktree to the "main" branch.
#   4. Merges the specified branch into main, with proper error checking.
#   5. Uses "git worktree list" to retrieve all active worktrees (under ~/dev
#      and matching the naming pattern) and removes them.
#   6. Deletes each branch that was created for a worktree (skipping "main").
wtmerge() {
  # Ensure exactly one argument is passed: the branch to merge.
  if [ $# -ne 1 ]; then
    echo "Usage: wtmerge <branch-to-keep>"
    return 1
  fi

  local branch_to_keep="$1"

  # Determine the repository root and its name.
  local repo_root repo_name
  repo_root=$(git rev-parse --show-toplevel) || {
    echo "Error: Not a git repository."
    return 1
  }
  repo_name=$(basename "$repo_root")

  # Fixed parent directory where worktrees are located.
  local worktree_parent="$HOME/dev"

  # Retrieve all active worktrees (from git worktree list) that match our naming convention.
  local worktrees=()
  while IFS= read -r line; do
    # Extract the worktree path (first field)
    local wt_path
    wt_path=$(echo "$line" | awk '{print $1}')
    # Only consider worktrees under our fixed parent directory that match "<repo_name>-*"
    if [[ "$wt_path" == "$worktree_parent/${repo_name}-"* ]]; then
      worktrees+=("$wt_path")
    fi
  done < <(git worktree list)

  # Check that the target branch worktree exists.
  local target_worktree=""
  for wt in "${worktrees[@]}"; do
    if [[ "$wt" == "$worktree_parent/${repo_name}-${branch_to_keep}" ]]; then
      target_worktree="$wt"
      break
    fi
  done

  if [[ -z "$target_worktree" ]]; then
    echo "Error: No active worktree found for branch '${branch_to_keep}' under ${worktree_parent}."
    return 1
  fi

  # Step 1: In the target worktree, check for uncommitted changes.
  echo "Checking for uncommitted changes in worktree for branch '${branch_to_keep}'..."
  if ! ( cd "$target_worktree" && git diff --quiet && git diff --cached --quiet ); then
    echo "Changes detected in branch '${branch_to_keep}'. Attempting auto-commit..."
    if ! ( cd "$target_worktree" &&
            git add . &&
            git commit -m "chore: auto-commit changes in '${branch_to_keep}' before merge" ); then
      echo "Error: Auto-commit failed in branch '${branch_to_keep}'. Aborting merge."
      return 1
    else
      echo "Auto-commit successful in branch '${branch_to_keep}'."
    fi
  else
    echo "No uncommitted changes found in branch '${branch_to_keep}'."
  fi

  # Step 2: Switch to the main worktree (assumed to be the current directory) and check out main.
  echo "Switching to 'main' branch in the main worktree..."
  if ! git checkout main; then
    echo "Error: Failed to switch to 'main' branch."
    return 1
  fi

  # Step 3: Merge the target branch into main.
  echo "Merging branch '${branch_to_keep}' into 'main'..."
  if ! git merge "${branch_to_keep}" -m "feat: merge changes from '${branch_to_keep}'"; then
    echo "Error: Merge failed. Please resolve conflicts and try again."
    return 1
  fi

  # Step 4: Remove all worktrees that were created via wtree().
  echo "Cleaning up worktrees and deleting temporary branches..."
  for wt in "${worktrees[@]}"; do
    # Extract branch name from worktree path.
    local wt_branch
    wt_branch=$(basename "$wt")
    wt_branch=${wt_branch#${repo_name}-}  # Remove the repo name prefix

    echo "Processing worktree for branch '${wt_branch}' at ${wt}..."
    # Remove the worktree using --force to ensure removal.
    if git worktree remove "$wt" --force; then
      echo "Worktree at ${wt} removed."
    else
      echo "Warning: Failed to remove worktree at ${wt}."
    fi

    # Do not delete the 'main' branch.
    if [[ "$wt_branch" != "main" ]]; then
      if git branch -D "$wt_branch"; then
        echo "Branch '${wt_branch}' deleted."
      else
        echo "Warning: Failed to delete branch '${wt_branch}'."
      fi
    fi
  done

  echo "Merge complete: Branch '${branch_to_keep}' merged into 'main', and all worktrees cleaned up."
}
```


Launch Multiple Cursor Composer AI Agents to Work in Parallel

AI-generated code often comes riddled with errors, especially TypeScript errors.  Trying to fix these *one by one* with in-editor AI tools (like Cursor's "Fix with AI") can be slow, frustrating, and sometimes even *introduce* new problems.  The fixes can be too localized, missing the bigger picture.

This lesson demonstrates a more efficient workflow: leveraging the power of **reasoning models** (like those found in AI Studio or advanced ChatGPT models) to fix errors *in bulk*.

Here's the process:

1.  **Identify All Errors:** Use the "Problems" panel in your editor to get a comprehensive list of all errors in the file.  Don't try to fix them individually yet! (Use `Cmd/Ctrl + Shift + P`, then type "problems".)
2.  **Gather Context:**
    *   Copy the *entire file's code*.
    *   Copy the *entire list of errors* from the Problems panel.
3.  **Prompt the Reasoning Model:** Paste *both* the code and the error list into a reasoning model.  Your prompt should be something like:  "Please fix all of these errors and rewrite the entire file with the corrections."  The key is to give the AI the *full context*. Wrap your code with XML tags to help the AI recognize it.
4.  **Iterate (if needed):**  Copy the corrected code back into your editor.  If a few errors remain, *now* it's time to use in-editor AI tools (like Cursor's Composer or "Fix with AI") for the final cleanup. These tools are better suited for small, isolated issues.
5.  **Provide Additional Context (for Stubborn Errors):** If a specific error persists (e.g., related to a library like `yargs`), provide *even more* context to the AI:
    *   Include links to the library's documentation (NPM page, official docs).
    *   Use Cursor's `@` feature to add specific files or documentation to the context.
6. Make sure to test! Run `npm test` or whichever testing command you're using for this project.

**Why this works:**

*   **Holistic Understanding:** Reasoning models excel at understanding the *relationships* between different parts of the code. They can see how a change in one place affects others, leading to more consistent and correct fixes.
*   **Efficiency:** Fixing multiple errors in a single pass is *much* faster than addressing them individually.
*   **Reduced "Whack-a-Mole":**  Fixing one error often reveals another.  Bulk fixing with a reasoning model minimizes this frustrating cycle.

This lesson teaches you a practical, powerful technique to tame AI-generated code and get it working quickly, even when it arrives full of errors. By combining the strengths of reasoning models and in-editor AI, you'll become a more efficient and confident developer.


Bulk Fixing AI-Generated Code Errors with Reasoning Models and Cursor Composer

[https://github.com/johnlindquist/mcp-cursor-tool-starter/tree/main](https://github.com/johnlindquist/mcp-cursor-tool-starter/tree/main)

Cursor's AI is powerful, but it can't do everything. What if you could give it the ability to interact with your specific workflows, tools, and data? This lesson shows you how to do exactly that by building a custom MCP tool – and we'll do it in under two minutes!

We'll leverage the Model Context Protocol (MCP), an open standard that bridges the gap between AI agents (like Cursor's Composer) and your custom code. By creating an MCP tool, you're essentially giving Cursor a new skill.

Here's the breakdown:

Understanding MCP: We'll briefly cover what the Model Context Protocol (MCP) is and why it's the key to extending Cursor's functionality. In short, it enables communication between the AI and your tools in a standardized way.

Fast Track Setup: We'll use a ready-made starter project (a single TypeScript file and package.json) to skip the boilerplate and get straight to the core concepts.

Step-by-Step Integration: We'll walk through the simple process of:

Cloning the starter project.

Installing dependencies with pnpm install.

Running the starter server.

Adding the tool to Cursor's MCP settings (under Features > MCP).

Verifying that your tool is working

Real-World Example: We'll demonstrate the tool in action, using Cursor's Composer to create a new GitHub issue using the gh CLI, all driven by our custom MCP tool.

This lesson is about more than just building one tool; it's about understanding how to extend Cursor's capabilities to fit your unique development needs. You'll learn the foundational steps to create a whole ecosystem of AI-powered tools.

Build Your First MCP Tool in Cursor in Just 2 Minutes

Install `ghx` with `npm i -g @johnlindquist/ghx`

https://github.com/johnlindquist/ghx

You've copied and pasted code, set up your project, and... *error*.  "Stream is not readable."  Sound familiar?  Generic Google searches and outdated Stack Overflow answers often leave you more confused than when you started.  You need more than just documentation; you need *context*.  You need to see how real developers solve this *exact* problem.

This lesson shows you a better way to debug, using real-world GitHub examples and the power of Cursor's Composer.

Here's the workflow we'll cover:

1.  **Identify the Error:** You've already done this!  You have a specific error message ("Stream is not readable") and the code that's causing it.
2.  **Find Real-World Solutions with `ghx`:** We'll use `ghx`, a tool for searching GitHub, to find *actual projects* that have encountered (and solved!) this same issue.  No more generic advice – you'll see working code.
3.  **Consolidate and Analyze:**  `ghx` brings those relevant code snippets into a single, easy-to-read file.
4.  **Leverage Cursor's Composer:** We'll use Cursor's Composer to directly interact with the examples and your problematic code.  Paste in your error, reference the `ghx`-generated file, and ask targeted questions like:
    *   "Based on these examples, how should I modify my code to fix the 'stream is not readable' error?"
    *   "What's the common cause of this error in the context of an MCP server?"
    *   "Show me the specific lines in the examples that handle stream readability correctly."
5. **Fix the Error:** Implement the solution using this workflow.

Instead of guessing, you'll learn directly from proven solutions.  You'll gain a deeper understanding of your issue and how to troubleshoot it effectively.  This approach transforms debugging from a frustrating hunt into a targeted learning experience.

Fix Real-World Coding Errors with GitHub Context through ghx and Cursor Composer

AI is amazing for generating code, but often leaves us staring at functions and libraries we've never seen before. This creates a huge problem: When things break (and they will break), we're lost. We don't understand the individual pieces, let alone how they interact. Knowing one part isn't enough; we need to see how unfamiliar components work together.

The solution? Real-world examples.

This lesson introduces ghx, a tool I built to do exactly that. ghx searches GitHub, finding actual code examples that use the specific combinations of functions and libraries that are tripping you up. Instead of generic documentation, you get concrete implementations. You can find the ghx repository at https://github.com/johnlindquist/ghx.

Here's the workflow we cover:

Identify the Unknown: Pinpoint the AI-generated code you don't understand – specific functions, libraries, or their interactions.

Search with ghx: Use ghx to search GitHub for examples using those terms together. ghx finds repos where those elements co-exist.

Consolidate Examples: ghx combines the relevant code snippets from those examples into a single, digestible file.

Ask the AI (Again, but Better!): Feed this consolidated code to an AI (like a coding-focused model in an AI studio). Now, instead of asking general questions, you can ask targeted questions based on real-world usage:

"Explain how these functions are used together in these examples."

"What are some common use cases for this combination of libraries?"

"Show me alternative code snippets that achieve the same result."

"Can you identify potential problems or areas for improvement, based on these examples?"

Iterate. Use your improved understanding to make changes, and then repeat the process to debug.

By leveraging ghx and targeted AI prompting, we transform from being lost in a sea of unfamiliar code to actively learning from how others have solved similar problems. We gain a deeper understanding of our AI-generated codebase, making debugging, modification, and future development far more manageable. This gives you the tools to understand, debug and improve your own code.

How to Work with AI-Generated Code You Don't Understand with ghx and Gemini

This lesson demonstrates how to utilize DeepSeek's R1 model to access its reasoning capabilities and then seamlessly transition to other models for subsequent tasks. By extracting the reasoning output from DeepSeek R1, you can leverage its powerful reasoning while gaining the speed, cost efficiency, and configuration flexibility of alternative models. This two-phase approach begins with DeepSeek’s new R1 model, praised for its open-source nature and value. You then gain the adaptability to switch to other models depending on your needs or existing workflows. This lesson provides a step-by-step walkthrough of this process, along with demo code to help you implement this technique yourself.

Combine DeepSeek R1 Reasoning with GPT 3.5 Turbo for the Cheapest, Fastest, and Best AI

While much focus in AI has been on optimizing input and generating concise outputs, a new model in Google's AI Studio dramatically expands output possibilities with a capacity of 65,000 tokens. This represents a significant shift, opening doors to new application scenarios, especially for developers and creators. This lesson explores a practical and immediately useful scenario: leveraging this large output capability within Google's AI Studio to generate extensive sample datasets for your projects. Whether you are developing a new application, building a resource, or require robust datasets for testing and validation, this model offers a powerful solution. We'll demonstrate how to move beyond the constraints of short responses and utilize the full potential of large output models to generate the data volume and variety you need, enhancing your development workflow through Google's AI Studio.

AI Studio's New 65k Output Opens Exciting Possibilities

This lesson explores how to use Cursor to generate and maintain English specifications as a form of living documentation. Learn how these automatically created documents can serve as a consistent and up-to-date representation of your code's behavior. The video highlights how reviewing and refining these English specifications can help ensure that code modifications align with the intended purpose and that documentation accurately reflects the current codebase, promoting better long-term code maintainability and clarity.

Here's the "english-spec.md" used in the video:

```markdown
> You are an AI specialized in analyzing source code and producing structured, plain-English representations of its functionality.  
>  
> **Your Task**:  
> 1. Read and interpret the code I provide.  
> 2. Produce a technical, English-only summary of what the code does.  
> 3. Use headings and bullet points to clearly outline the roles of each function, class, variable, or important logic block.  
> 4. **Do not include any actual code** in your final output. Instead, translate the code’s content into an English explanation (like a specification or documentation).  
> 5. Keep the explanation concise but thorough. Focus on explaining the purpose, process, and relationships between functions or modules in the code.  

**User Prompt to the AI**:

> **Instruction**: Convert the following code into a single file of pure English text that outlines exactly what each part of the code does. Use bullet points, headings, and descriptive language. Do not show any code—only explain how the code behaves. This is intended to serve as a human-readable spec or “translation” of the code.  
>  
> **Code**:  
> ~~~  
> [PASTE YOUR CODE HERE]  
> ~~~  

**Example Input/Output #1**:

- **Example Code (Input):**
  ~~~js
  // example1.js
  const greetUser = (userName) => {
    const greeting = `Hello, ${userName}!`;
    console.log(greeting);
  };

  greetUser("Alice");
  ~~~

- **Example Explanation (Output)**:
  ~~~
  # Overview
  - This file defines a single function which greets a user by name and prints a message to the console.
  
  # Function: greetUser
  - Accepts one parameter (`userName`).
  - Constructs a greeting string that combines static text with the `userName`.
  - Outputs the greeting using `console.log`.

  # Behavior Flow
  - The function is called with the argument "Alice".
  - Upon invocation, "Hello, Alice!" is logged to the console.

  # Key Points
  - Shows how to create a greeting with a dynamic name.
  - Demonstrates basic string interpolation and console logging.
  ~~~

**Example Input/Output #2**:

- **Example Code (Input):**
  ~~~py
  # example2.py
  class Calculator:
      def __init__(self, initial=0):
          self.value = initial
      
      def add(self, amount):
          self.value += amount
      
      def subtract(self, amount):
          self.value -= amount
      
      def get_value(self):
          return self.value

  calc = Calculator(10)
  calc.add(5)
  calc.subtract(3)
  result = calc.get_value()
  print(result)
  ~~~

- **Example Explanation (Output):**
  ~~~
  # Overview
  - This file defines a `Calculator` class that keeps track of an internal numerical value and provides methods to modify it.
  
  # Class: Calculator
  - **Constructor** (`__init__`):
    - Accepts an optional initial value (default is 0).
    - Stores the initial value in a `value` property.
  - **Method: add**:
    - Takes an `amount` and increments the internal `value` by that amount.
  - **Method: subtract**:
    - Takes an `amount` and decrements the internal `value` by that amount.
  - **Method: get_value**:
    - Returns the current internal `value`.
  
  # Behavior Flow
  - An instance of `Calculator` is created with an initial value of 10.
  - The `add` method is called with 5, raising the value to 15.
  - The `subtract` method is called with 3, lowering the value to 12.
  - The `get_value` method is called to retrieve the current value (12).
  - The result (12) is printed to the console.

  # Key Points
  - Demonstrates basic OOP with a class that manages state.
  - Showcases constructor, addition, subtraction, and retrieval of a stored value.
  ~~~  

---

## Final Prompt

Below is a full, combined version of the prompt you can provide to an AI to guide it in generating the English-only, bullet-pointed explanation. Feel free to modify or adapt this as needed:

~~~
You are an AI specialized in analyzing source code and producing structured, plain-English representations of its functionality.

Your Task:
1. Read and interpret the code I provide.
2. Produce a technical, English-only summary of what the code does.
3. Use headings (e.g. # Overview, # Functions, # Classes, # Behavior Flow) and bullet points.
4. Do not include any code in your final output—only explain how the code behaves.
5. Keep it concise but thorough, focusing on purpose, process, and relationships between functions or modules.

Below are some examples of how code might be transformed into an English-only explanation:

Example Input:
-------------------
~~~js
// example1.js
const greetUser = (userName) => {
  const greeting = `Hello, ${userName}!`;
  console.log(greeting);
};

greetUser("Alice");
~~~
Example Output:
-------------------
# Overview
- This file defines a single function which greets a user by name and prints a message to the console.

# Function: greetUser
- Accepts one parameter (`userName`).
- Constructs a greeting string that combines static text with the `userName`.
- Outputs the greeting using `console.log`.

# Behavior Flow
- The function is called with the argument "Alice".
- Upon invocation, "Hello, Alice!" is logged to the console.

# Key Points
- Shows how to create a greeting with a dynamic name.
- Demonstrates basic string interpolation and console logging.


Example Input:
-------------------
~~~py
# example2.py
class Calculator:
    def __init__(self, initial=0):
        self.value = initial
    
    def add(self, amount):
        self.value += amount
    
    def subtract(self, amount):
        self.value -= amount
    
    def get_value(self):
        return self.value

calc = Calculator(10)
calc.add(5)
calc.subtract(3)
result = calc.get_value()
print(result)
~~~
Example Output:
-------------------
# Overview
- This file defines a `Calculator` class that keeps track of an internal numerical value and provides methods to modify it.

# Class: Calculator
- **Constructor** (`__init__`):
  - Accepts an optional initial value (default is 0).
  - Stores the initial value in a `value` property.
- **Method: add**:
  - Takes an `amount` and increments the internal `value` by that amount.
- **Method: subtract**:
  - Takes an `amount` and decrements the internal `value` by that amount.
- **Method: get_value**:
  - Returns the current internal `value`.

# Behavior Flow
- An instance of `Calculator` is created with an initial value of 10.
- The `add` method is called with 5, raising the value to 15.
- The `subtract` method is called with 3, lowering the value to 12.
- The `get_value` method is called to retrieve the current value (12).
- The result (12) is printed to the console.

# Key Points
- Demonstrates basic OOP with a class that manages state.
- Showcases constructor, addition, subtraction, and retrieval of a stored value.

---

**Now**: Please apply the same conversion process to the following code. Convert it into a plain-English document that describes what the code does in detail, using bullet points and headings. Create the document next to the original with the filename as `${fileName}.md`. Do not include any source code in the output—only the explanation:

[INSERT YOUR CODE HERE]
```

Programming in English with Cursor

In this lesson, you'll learn how to enhance the accuracy of components generated by Cursor Composer by aligning your project's package.json with Cursor's rules. We'll guide you through extracting the list of installed packages from your package.json and incorporating them into your .cursorrules file, along with brief descriptions of their functionalities. By providing Cursor with this contextual information, you'll enable it to generate components that are more precise and functional on the first attempt. The lesson includes demonstrations of component generation both with and without these enhancements, highlighting the improvements in accuracy and efficiency.

Boost Cursor Composer Accuracy: Integrating package.json with Cursor Rules

Speed up your bug-fixing process dramatically with Cursors Composer. Take a warning from your logs, search for relevant terms, then seamlessly import both the warning and search results into Composer. Add documentation and apply fixes to all search results in one go. This streamlined workflow resolves multiple issues rapidly, saving valuable development time.

Batch Fix Every File in Search Results with Cursor's Composer

You know when you're deep in the code trenches and need someone to challenge your assumptions? That's exactly what this is about.

Instead of waiting for someone to poke holes in your master plan, you can paste that strategy straight into AI Studio and let it pressure test your ideas. We're talking about using this tool to validate everything from your feature proposals to your ambitious refactoring strategies.

The real magic happens when you hit that microphone button. Now you're in a real-time verbal sparring match. It's like rubber duck debugging but the duck actually pushes back and makes you defend every architectural decision you've made.

Here's the workflow:
1. Drop your master plan into the system instructions
2. Tell the AI to challenge every assumption
3. Hit that mic and defend your choices like you mean it
4. Watch your plan either emerge stronger or get rightfully dismantled

This approach is perfect when you're:
- Stuck in your own head with a complex problem
- Need to validate if your approach holds water
- Want to catch edge cases before they catch you
- Looking for opportunities you might have missed because you're too close to the code

It's like having a senior dev on call 24/7, ready to challenge your ideas and push you to think deeper about your solutions.

Now go forth and get your ideas challenged. Your projects will thank you for it.


An Uncomfortable and Challenging Conversation with AI Studio

In this lesson, you'll learn how to effectively brainstorm your project ideas before working with AI agents. We'll cover:

1. The importance of having a clear plan before starting work with AI agents
2. Using traditional brainstorming techniques to gather your thoughts
3. Leveraging video recording to capture your brainstorming session
4. How to review and analyze websites for inspiration
5. Documenting likes, dislikes, and potential features for your project
6. Using AI tools (like AI Studio) to organize and process your recorded brainstorming session

The lesson emphasizes a modern approach to brainstorming that combines traditional techniques with video recording, making it easier to later process your ideas through AI tools. This method helps ensure that no ideas are lost and that your thoughts can be effectively organized by AI for future reference.

How to Brainstorm Your Project Features to Prepare for AI Agents

Many people share .cursorrules files, but trying to craft your own from scratch is a huge pain. Instead, this lesson shows you how to grab ALL community-created .cursorrules files to build a custom rule set for your projects. We'll use Gitingest and Google AI Studio to gather these examples and generate an awesome starting point customized to your specific project.

Generate Custom .cursorrules for Your Project Based on Community Examples

The GitHub CLI allows you to search issues and filter on different criteria like amount of comments. This allows you to search for real-world situations and pains/solutions people have using different technology. 

With the GitHub CLI in hand we'll drop 100s of issues as context in Googles AI Studio and have Gemini determine the 10 most frequently asked questions. This will give us a sense of how people use a library and where people get hung up.

Search 100s of Issues with GitHub CLI as Context for AI Studio

I often find myself wondering how to use certain APIs in certain situations, and I have a couple of keywords that I try and search up on Google. 

What you can do in this situation is turn to GitHub and see how other people have actually used this code on public projects. The GitHub CLI enables us to run searches like this, and we can take the results and work on them programmatically.

Inside of Cursor with their Composer AI agent, we can search for the files we want, tell the agent to download them, and inspect them for better understanding of how those things work together.

Search All of GitHub's Code and Pass the Results to AI Agents in Cursor

The most difficult tasks will require the strongest AI models. And those models simply aren't available as AI agents inside of your tooling. So the best workflows are to drag and drop the files you need to be changed and analyzed inside of a reasoning model such as OpenAI's O1 Pro, then letting it create a giant plan for your dumber AI agents to work on. The key here is that instead of just copying and pasting the entire plan into Cursors Composer or your AI agent, it's to create a file inside of your project and ask your agent to tackle the plan one step at a time. This allows you ample opportunity between each step to test and verify the micro steps along the way. Otherwise, as I've experienced many times, a session can go way off track and you burn a lot of time and burn a lot of AI requests Cursors Composer and it starts churning through a plan Cursors Composer and making lots of unwanted changes. Cursors Composer and it's to guide an AI agent to hold its hand along the way, especially through the most complex tasks. Cursors Composer and the most complex tasks Cursors Composer and the most complex tasks require a step-by-step plan.

Planning AI Agent Sessions with Reasoning Models

AI agents will inevitably make mistakes—it's just a matter of when. A key tool in your toolbox, once they do make mistakes after working on a problem for a while, is to use **git diff** to capture all of the changes they've made. 

Once you have those changes in a text file, you have a portable document that you can test against other AI models. This allows you to move the problem into smarter reasoning models with smaller context windows, helping you isolate and focus on the issue at hand.

**git diff** has been invaluable when working with AI agents because they'll often make many good changes but also slip in one tiny error. Finding that one small mistake is **git diff**’s superpower.

Leverage Git Diff to Fix AI Agents' Mistakes

AI agents are notorious for getting tasks done but also taking some shortcuts in TypeScript such as falling back to using things like 'any', which you probably do not want in your codebase.

This creates a scenario where the AI has done all of the work, you've tested and verified everything, but it's left you with data and functions untyped. So in this situation, when you run git commit, you can set up a commit hook to expose all the TypeScript errors then you just let the AI agent run that commit hook and it can find all of the mistakes that it made and go through and fix everything without you ever having to touch the code.

This lesson covers a real world scenario of a commit hook running based on a refactor that was made when extracting some types. You will learn how Cursor AI agents handle and respond to commit hooks and by giving exhaustive information on what went wrong in a commit, the agent can continue on and make all the changes for you.

Commit Hooks are Critical with AI Agents in Cursor

If you ever want to see data represented in a certain way, such as a chart or a graph, to better understand what's going on in the world, you can use AI's to grab the most recent data and then convert it into any visual format you want. This is enabled in AI studio with Gemini through what's called grounding from web search, structured output formatting data, and code execution, which can run Python and generate charts. This lesson is going to walk you through the challenges of using grounding, especially when working with numbers which need to be accurate. How you can use image recognition and convert that to structured output. And then the challenges of using code execution. Especially when AI's are confident that the code ran even though the code failed. At the end, we still get to generating a chart through the online editor and then we take it also to set up in Cursor in a local environment where we can run all the way through YOLO mode and just click around some buttons and get our chart.

Generate Charts from Current Events with Gemini's Structured Output and Code Execution

Warning: AI's make mistakes. Some of them can be _very_ costly. Terminal have access to your most private information, especially if you're using a "work computer". Please proceed with extreme caution!

Cursor's new "YOLO" feature It allows you to enter an AI prompt and then just sit back and watch as an AI will run terminal commands automatically. The AI will automatically install packages, automatically start and stop dev servers, and even check the output of the terminal commands to run subsequent terminal commands and attempt to fix them.

Traditionally, this is some of the most critical, but also some of the most boring work that a developer has to do, especially when it comes to memorizing all of the various syntax and all of their various commands that you need to know. In larger projects, it's even really easy to forget which commands are even available. So handing all this work over to an AI is a natural step in the evolution of development. But again, please be extremely cautious with these features as there are a million ways that everything could go terribly, horribly wrong.

AI YOLO - Sit Back and Watch Cursor Automatically Run Terminal Commands

You will learn how to create and manage complex, nested schemas using a real world example (room bookings with guest details) used throughout all lessons. All created schemas are tested against potential bugs and we verify error messages.

The course covers topics such as:

- Utilizing Zod's shape and unwrap features to perform partial validations without losing the overall schema structure.
- Managing optional, nullable and nullish properties.
- Implementing unions and intersections to handle different types of data.
- Ensuring type safety with sets and maps, including custom validation logic for primitive values.
- Creating custom error messages for improved user feedback.

Get a solid understanding of how to leverage Zod to enhance runtime data validation in JavaScript/TypeScript applications 🔥

Tomasz Ducin

Advanced Type Checks with Zod

Get a solid understanding of how to leverage Zod to enhance runtime data validation in JavaScript or TypeScript applications

In this lesson, we learn that when querying MongoDB collections, we can control which properties are returned by using projections with the `findOne` method.

We demonstrate how to include or exclude fields by setting them to 1 or 0, respectively. For example, we can choose to include the name and position while excluding the `_id` field.

We also cover how to access nested properties and project specific elements from arrays using the `$slice` operator, allowing for more precise data retrieval based on our needs.

Return a subset of properties of a MongoDB Document (projections, $slice)

Return specific properties from MongoDB documents using projections in the findOne method, including nested fields and array slicing, $slice

In this lesson, we learn that counting documents that meet certain criteria in MongoDB can be done with the countDocuments() method.

We demonstrate how to retrieve the total number of documents when no query is specified and how to filter results using regular expressions.

For example, we can count employees with names containing a lowercase "a" or those with specific skills, using `$regex`.

Additionally, we show how to count documents where age is not equal to a given value, illustrating the versatility of the `countDocuments()` method in various scenarios.


Count documents satisfying a query in MongoDB Collection (countDocuments, $regex, $in)

Count documents in MongoDB collections using countDocuments() with query filters, including regex and specific conditions, using $regex, $in

In this lesson, we learn that searching for a MongoDB document by its ID can be a little tricky in the beginning.

We demonstrate how to use the `_id` field to search for specific documents and emphasize the necessity of wrapping the ID with the `ObjectId` constructor. This step is crucial because failing to do so can result in empty results, underscoring the importance of proper syntax when querying by document ID.


Find Document by id in MongoDB Collections

Find MongoDB documents by their unique _id using the ObjectId constructor without mistakes.

In this lesson, we learn that we can perform advanced filtering in MongoDB by using expressions within our queries. All thanks to `$expr`.

We demonstrate how to compare multiple document properties, such as ensuring age is less than salary using comparison operators (`$lt`, `$lte`, `$gt`, `$in`, `$nin`, etc).

Additionally, we explore filtering based on the length of an array (`$size`) to check for specific skills.


Filtering Documents using Expressions in MongoDB Collections ($expr, $size, $in, $and, etc)

Filter MongoDB documents using expressions $expr with comparison operators $lt, $gt, $eq and array length checks $size

In this lesson, we learn that combining multiple criteria in MongoDB queries can be done using logical operators such as `$and` and `$or`.

We demonstrate how to create queries that filter documents based on various conditions, such as _age_ and _skills_.

Additionally, we explore the use of the `$in` operator for matching any values in an array and the `$all` operator for ensuring all specified values are present.

This lesson provides essential skills for effective use of operators such as: `$in`, `$nin`, `$lt`, `$lte`, `$gt`, `$gte`, `$eq`, `$ne` (and many others) in querying MongoDB collections.



Combine Filtering Documents in MongoDB Collections ($and, $or, $in, $eq, etc)

Combine filtering criteria in MongoDB with logical operators like $and, $or; use $in and $all for array filtering in this lesson on document queries.

In this lesson, we learn that filtering documents from MongoDB collections can be achieved through the `find` and `findOne` methods.

We demonstrate how to use these methods to retrieve documents based on specific criteria, such as names or emails, and how to apply regular expressions for more general searches.

Additionally, we explore filtering by array values and using conditions like less than or greater than for numerical properties.


Filtering Documents in MongoDB Collections (find, findOne)

Learn to filter MongoDB documents using find and findOne methods with query criteria, regex, and array filtering in this lesson on document retrieval.