Heads up - this is a draft. Part of an experiment: publishing rough-but-timely versions of half-finished posts to a separate Drafts feed, instead of letting them rot in a folder while the tooling moves on without them. Expect: accurate commands, missing screenshots, and the occasional bit that needs a second pass. If you spot something to add, fix, or improve, let me know - I’d rather get it right than perfect.

How much time did your team waste this week searching for answers that already exist somewhere?

New engineer asks: “How does authentication work in our system?” PM asks: “Has anyone touched this API field before?” Support asks: “Where’s the documentation for this feature?”

And everyone does the same thing: searches Confluence, digs through Jira, posts in Slack, waits for someone who knows. Hours disappear into the void.

I’ve been experimenting a lot with NotebookLM for the past few months to solve exactly this problem. It’s not perfect - the UX is frustrating and file management is terrible - but it’s solving real problems I couldn’t solve easily before.

Here are 6 use cases you can copy, step-by-step.

Use Case #1: Tool Documentation Agents (Internal Help Desk)

The Problem (Before AI)

Your team uses Cursor, or Jira, or whatever internal tool. Someone new joins and can’t figure out how to configure something basic. They ask in Slack. Someone answers. Next week, someone else asks the same question. Repeat indefinitely.

Information is scattered across help docs, wikis, Slack threads nobody can find. Support burden falls on specific people who become bottlenecks. New team members take months to get up to speed because finding answers takes forever.

Only 12% of employees feel their organization does great onboarding. And here’s what kills me: 42% of workers say the knowledge they need is unique to their context. Generic documentation doesn’t cut it. You need something that understands YOUR tool stack.

The AI Solution

I’ve built agents for Cursor, NotebookLM, Claude code, Hex, Snowflake, internal tools - takes about 30-60 minutes once, saves hours every week. Here’s exactly how to do it.

STEP-BY-STEP WORKFLOW

1. Gather Documentation Links

• Go to tool homepage and dev docs homepage

• You need the parent page with the tree structure in the nav bar

• Not individual pages - the main page that links to everything

2. Extract All Links

• Install Link Klipper Chrome extension

• Run it on the docs page

• Exports a CSV of every link in the navigation

• Takes about 30 seconds

3. Use my Agent Builder Bot

Link here → Prompt and agent builder

• Use my “Agent Builder” on the ChatGPT Store

• Tell it: “I’m building an agent for [tool name]”

• Bot walks you through refinement

• Type “ok, go” at any point for directions

4. Give Bot the Context

• Upload the CSV of links

• Say “that’ll be the context for the agent”

• Bot rewrites the instructions to match

5. Upload to NotebookLM

• Go to NotebookLM

• Upload the markdown custom instructions from agent builder

• This becomes your bot’s “personality”

6. Rename for Organization

• Start filename with “A” or number + name

• Example: “A-Cursor-Bot” or “01-Cursor-Documentation”

• Why? NotebookLM sorting is absolute crap. This keeps it findable.

7. Upload Link CSV

• Use NotebookLM’s link uploader

• Upload the CSV of links

• NotebookLM scrapes every link and adds as context

• Takes a few minutes depending on how many pages

8. Test the Bot

• Ask questions about the tool

• Bot sources only from provided context

• Provides direct URL links to help docs

• Check that answers make sense

9. Share with Team

• Create Google Group for access control

• Share notebook with the group (group could also just be everyone in your company)

• Everyone gets access to same knowledge base

Tools Used

• Link Klipper (Chrome extension)

• Agent Builder Bot (GPT Store)

• NotebookLM (Google - free with Workspace)

• Google Groups (sharing)

Why This Works

NotebookLM only sources from what you give it. That’s the key. It won’t make up answers or pull from the wider internet. You get citations with direct links. The team can maintain and update it centrally. And it’s free if you’re already using Google Workspace.

Here’s what makes this actually useful: new team members reach expert-level knowledge 4x faster when they have instant, sourced answers. Instead of 8 months to get up to speed, imagine 2 months. That’s not hype - that’s from actually watching people onboard with this vs without.

Time Savings

• One-time setup: ~30-60 minutes

• Ongoing: No support burden for common questions

• Team finds answers instantly vs asking in Slack

The hidden time saver? You stop “explaining something to one person at a time.” When you find yourself answering the same question for the third time, that’s your signal to build this.

Gotchas & Lessons Learned

• NotebookLM UX is terrible (I cannot stress this enough)

• There exists chrome extensions now you can use for bulk deletion of source files

• File management is crap - name files strategically

• Multiple instruction sets possible (say “follow instruction set XYZ”)

• Save really good answers as notes or they get deleted/lost

• Pictures don’t get scraped and aren’t supported

• Can’t have personal notes - sharing shows all notes to everyone

Use Cases

• Cursor documentation bot (what I built first)

• Internal tool help desks

• Onboarding new team members

• Reducing support ticket burden

• Engineering tool documentation

Replication Guide

1. Find tool’s documentation homepage with nav tree

2. Install Link Klipper Chrome extension

3. Export CSV of all documentation links

4. Find “Agent Builder Bot” on GPT Store

5. Tell bot what tool you’re documenting

6. Provide CSV, let bot refine instructions

7. Upload bot’s markdown output to NotebookLM

8. Rename with A-prefix or number for sorting

9. Upload CSV to NotebookLM’s link uploader

10. Create Google Group and share notebook

11. Test with common questions your team actually asks

Use Case #2: Mind Map Project Discovery (Visual Navigation)

The Problem (Before AI)

You’re starting a complex project. Documentation is overwhelming. Stakeholders need different views of the same information. Leadership wants high-level overview. Engineering wants technical details. Product wants user journeys.

Information overload prevents quick understanding. You spend half your discovery time just helping people understand what you’re building.

I’ve found that product discovery typically takes 4 weeks minimum. But here’s what kills me: half that time is spent just helping people navigate what you’re building. Mind maps cut that navigation time dramatically.

The AI Solution

This one took me a while to figure out, but once I cracked it, I’ve used it on every major project since. You create multiple views of the same project - each optimized for different stakeholders.

STEP 1: Create Empty Template Structures

Ask AI (I use Cursor or ChatGPT) to generate empty documentation templates for different views:

• Stakeholder-sensitive view (what leadership needs)

• Salesforce stages view (what sales needs)

• Actor-based view (who does what)

• Team-based view (which team owns what)

• MVP vs GA vs Future view (timeline phases)

• Technical integration view (systems and APIs)

• Journey flow template (step-by-step user flows)

The templates have headers only, no content. NotebookLM fills them from your actual project docs.

STEP 2: Upload Templates to NotebookLM

• Create new NotebookLM project

• Upload ALL empty templates as sources

• Upload actual project documentation (user journeys, PRDs, discovery docs)

• Everything goes into one notebook

STEP 3: Generate Mind Maps

Here’s the trick:

• Turn OFF all sources except one empty template

• Click “Generate Mind Map” in Studio

• NotebookLM creates structured mind map from template headers

• Mind map buttons are clickable and interactive

STEP 4: Activate Full Context

• Turn ON all sources (templates + documentation)

• Refresh the mind map

• Now clicking any button pulls from full project context

• Each click provides sources and citations from your actual docs

STEP 5: Share with Stakeholders

Different stakeholders use different template mind maps:

• Sales team uses “Opportunity Stages View”

• Engineering uses “Technical Integration View”

• Leadership uses “Stakeholder-Sensitive View”

• Everyone has same underlying source of truth

The “Knowledge Tree” Prompt

I’ve refined this prompt over multiple projects. Run it in NotebookLM with your context already loaded:

Generate a structured outline document titled "[PROJECT NAME] Knowledge Tree" that maps this project's complete scope for mind mapping. Start with the project name as the title, then organize hierarchically:

PROJECT TITLE: [Extract the main project/product/initiative name from the sources and use as: "PROJECT_NAME Knowledge Tree"]

1. PROJECT FOUNDATION
- Name, mission, core value
- Current status & future vision
- Key differentiators
- Success metrics

2. SCOPE & BOUNDARIES
- Geographic/market coverage
- Product/service boundaries
- Target segments
- Constraints & limitations

3. CORE OFFERINGS
- Main products/services
- Features & capabilities
- User journeys
- Technical specifications

[... continues through 10 sections ...]

Format with clear headers and bullet points. Include specific data, metrics, and examples. Create a single comprehensive document optimized for mind map conversion.

IMPORTANT: Use the main project/initiative name from the sources as the document title in format: "[PROJECT_NAME] Knowledge Tree"

Then:

• Save output to note

• Save note to source

• Unselect all sources

• Select only the new note source

• Hit Mind Map button in Studio

• Once complete, select all sources again

• Mind map buttons now lead to full context sources

Tools Used

• NotebookLM (Google)

• Claude Code/Cursor (template generation)

• Mind Map Studio (NotebookLM feature)

Why This Works

Multiple views of the same information. Interactive, clickable navigation. Reduces cognitive load. Sources are always cited. You can regenerate mind maps by simply changing template headers.

Here’s what I’ve found: knowledge grows better in stable, long-lived teams, but documentation still matters. The problem is traditional docs don’t provide different views for different audiences. Mind maps solve this - leadership gets their high-level view, engineers get their technical view, everyone’s looking at the same truth.

Time Savings

• Creates comprehensive project overview in minutes vs hours

• Stakeholders self-serve for information

• Reduces “can you explain this again?” meetings

• Leadership gets quick visual understanding

Those “walk me through the project” meetings that take 30-60 minutes? Cut to 10 minutes with a mind map walkthrough. And stakeholders can explore on their own instead of booking your calendar.

Gotchas & Lessons Learned

• Must turn off sources before generating mind map from template (this confused me for days)

• Template headers drive mind map structure - choose carefully

• Can regenerate by simply editing template headers

• NotebookLM file management is still terrible

Use Cases

• Any project that requires documentation

• User journey visualization

• Complex feature documentation

• Cross-functional project coordination

• Product discovery presentations

Replication Guide

1. Use AI to generate 5-7 empty template structures (different views)

2. Create NotebookLM project

3. Upload all templates as sources

4. Upload project documentation

5. Turn off all sources except one template

6. Generate mind map in Studio

7. Turn all sources back on (except for the templates)

8. Use “Knowledge Tree” prompt for comprehensive view

9. Share different mind maps with different stakeholders

Use Case #3: Issue Investigation & Root Cause Analysis

The Problem (Before AI)

API field breaks in production. You need to find out if anyone touched this field before. Could be in any Jira ticket across years of history. Manual search takes hours or days.

Context is spread across multiple tickets. Hard to trace change history. You end up Slacking people: “Hey, did you work on this?” And waiting. And waiting.

Google’s SRE research emphasizes that postmortems should “fix systems and processes,” not just address symptoms. But you can’t fix the system if you don’t understand the full context of what happened. And that context is usually buried in tickets from 6 months ago that nobody remembers.

The AI Solution

I built a Python script for this (well, Cursor built it for me). Now I can find root cause in minutes instead of days.

WORKFLOW

1. Python Script Export (Done in Cursor/Claude code)

• Script exports keywords from Confluence and Jira

• Based on your search criteria

• Example: Search for specific API field name

• I run this script anytime something breaks

2. Generate Context File

• Script creates single MD file

• Contains all Jira tickets mentioning that field

• Includes all Confluence pages with context

• One file with everything relevant

3. Drop into NotebookLM

• Upload MD file as source

• Ask: “My team is having difficulty with [API field], can you help?”

• NotebookLM searches all tickets

4. Get Root Cause

• NotebookLM finds relevant tickets

• Provides sources (links to specific Jira tickets)

• Shows: “In this ticket, XYZ changed this field, which caused this validation error you’re seeing”

• Direct links to dig deeper

5. Incredibly Fast Discovery

• Root cause identified in minutes

• Can see pattern across multiple tickets

• Historical context nobody remembers

Alternative Approach: Full Jira Export

Don’t want to build a script? Here’s the lazy version that still works:

• Export entire Jira filter to PDF

• Drop PDF into NotebookLM

• Now have every Jira ticket your company has ever done

• Ask: “Has anyone touched this field?”

• NotebookLM searches everything with sources

Tools Used

• Python script (custom, built in Cursor)

• NotebookLM (Google)

• Jira export (PDF)

Why This Works

Searches historical context impossible to remember. Provides sources and citations, not just answers. Much faster than manual Jira searches. Can export entire Jira history. Sources only from your data - no hallucinations.

You’ll “never, ever again debug or understand this code as well as you do right now, with your original intent fresh in your brain.” But when you’re investigating an issue weeks or months later, you’ve lost that context. This approach gives you back the original context through historical tickets.

Time Savings

• Root cause in minutes vs hours/days

• No need to ask “who worked on this?”

• Historical context instantly accessible

• Reduces debugging time significantly

Stack Overflow research shows that teams with rapid feedback loops find more than 80% of bugs quickly. But what about the bugs that slip through? Those are the ones hiding in historical context. This workflow helps you find them fast.

Gotchas & Lessons Learned

• Python script is custom (build once, reuse forever)

• Jira filter export works for entire history

• Keep exports updated periodically (I do monthly)

• NotebookLM handles large PDFs well

Use Cases

• API field troubleshooting (my most common use)

• Bug investigation

• Feature change history

• “Who touched this last?” questions

• Understanding legacy decisions

Replication Guide

1. Build Python script (or use Cursor/Claude to generate)

2. Script exports keywords from Jira/Confluence

3. Or: Export Jira filter to PDF for full history

4. Upload to NotebookLM

5. Ask questions about specific fields/issues

6. Get sources with direct links to tickets

Use Case #4: Architecture Validation & Feasibility Checks

The Problem (Before AI)

New feature requirements might conflict with existing architecture. You need to validate against system documentation. Don’t want to break existing patterns. Manual review takes significant time.

You can’t just “ask the person who built it” if they’ve moved on or if the system has evolved. And reading through 50 pages of architecture docs to check one thing is nobody’s idea of a good time.

The AI Solution

This one saves me from making architectural mistakes before they happen.

WORKFLOW

1. Load System Documentation

• Upload architecture docs to NotebookLM

• Include coding standards

• Tech choice standards

• Existing system design docs

• All in one notebook

2. Upload New Requirements

• Add new feature PRD or spec

• Or just paste requirements as a note

3. Ask Validation Questions

• “Does this requirement fit our architecture?”

• “Can you suggest any changes we might need?”

• “What patterns should we follow for this?”

4. Get Conflict Analysis

• NotebookLM identifies conflicts

• Suggests architectural changes

• Example: “You need an extra event here, you need a new consumer for that event”

• Shows whether you can extend existing vs create new

Why This Works

NotebookLM sticks religiously to sources. Can ask it to suggest changes (it breaks out of constraints when you ask). Provides specific recommendations. Sources all suggestions from your docs. Prevents architectural drift.

Product discovery research emphasizes validating whether solutions are “usable, useful, and feasible” - this workflow handles the “feasible” part by checking against your actual system architecture, not theoretical constraints.

Tools Used

• NotebookLM (Google)

• System documentation (architecture, coding standards)

Time Savings

• Feasibility check in minutes vs hours

• Prevents architectural mistakes early

• Reduces back-and-forth with architects

• Catches conflicts before development

You’re not just saving time - you’re creating shared understanding. When the validation comes from your own architecture docs (with citations), there’s no argument about whether it fits or not.

Use Cases

• New feature validation

• Architecture review

• Tech stack alignment

• Coding standards compliance

Replication Guide

1. Upload system documentation to NotebookLM

2. Upload new requirement/PRD

3. Ask: “Does this fit our architecture?”

4. Ask: “Can you suggest changes needed?”

5. Review suggestions against sources

6. Use for early validation before development

Use Case #5: Historical Context Search (”Has Anyone Touched This?”)

The Problem (Before AI)

Need to know if specific field or feature was discussed before. Information buried in old Jira tickets. Can’t remember who worked on what. Need quick context for decisions.

Only 4% of companies consistently document their processes. The rest rely on tribal knowledge and scattered tickets. When someone leaves or moves teams, that knowledge evaporates.

The AI Solution

This is basically Use Case #3 but broader. Same script, different questions.

WORKFLOW

1. Export Full Jira History

• Export Jira filter to PDF (print details button when In a filter search)

• Can export entire company history (yes, really)

• One-time effort per quarter or whatever

2. Upload to NotebookLM

• Single upload of all tickets

• Takes a while first time

• Worth it

3. Ask Questions

• “Has anyone touched this field?”

• “What tickets mention [feature]?”

• “Who worked on [system]?”

• Any question about your project history

4. Get Sourced Answers

• NotebookLM finds all relevant tickets

• Provides direct links

• Shows context from each ticket

• No more digging through Jira manually

Alternative: Keyword-Based Export

• Use Python script (Use Case #3)

• Export only tickets matching keywords

• Smaller, more focused context file

• Faster searches

Tools Used

• Jira export (PDF)

• NotebookLM (Google)

• Python script (optional, for keyword filtering)

Why This Works

Company memory in searchable format. Sources with direct links. Faster than manual Jira searches. No hallucinations - only from your tickets.

If you’re explaining something to one person at a time, you need a better system. This is that system. Your entire team’s history, searchable with citations.

Time Savings

• Find historical context in seconds

• No need to ask team members

• Reduces “who worked on this?” Slack messages

Those Slack interruptions where someone asks “Hey, did we ever discuss [X]?” - they disappear. Team members find their own answers, sourced from actual tickets, without disrupting anyone’s flow.

Replication Guide

1. Export Jira filter to PDF (or use keyword script)

2. Upload to NotebookLM

3. Ask questions about fields/features/history

4. Get sourced answers with ticket links

Use Case #6: Stakeholder Directory & Team Context

The Problem (Before AI)

New to project or team. Don’t know who owns what. Need to understand team structure. Stakeholder personas unclear.

Only 12% of employees feel their organization does great onboarding. When you’re new to a project, figuring out “who should I talk to about X” can take weeks. This shortens it to minutes.

The AI Solution

I built this for a project of mine when I realized I couldn’t keep track of which team owned what.

WORKFLOW

1. Create Stakeholder Documentation

• Document team structure

• Roles and responsibilities

• Stakeholder personas

• Who owns what systems

2. Generate Mind Map (Use Case #2 method)

• Create team-based view template

• Upload to NotebookLM with team docs

• Generate mind map

3. Navigate by Team/Persona

• Click “Operations” → see Operations team context

• Click “Ops Analyst” → see persona details

• Click “Ops Manager” → see manager persona

• All sourced from your docs

4. Search for Context

• Ask about specific teams

• Get sourced information

• Understand relationships

Tools Used

• NotebookLM

• Mind Map Studio (NotebookLM feature)

• Stakeholder documentation

Why This Works

Visual directory of people and teams. Searchable team context. Onboarding new team members. Quick reference for cross-functional work.

Knowledge retention works best in stable teams, but you still need to understand who does what. Communities of practice help, but they require active participation. This gives you passive access to team context whenever you need it.

Time Savings

• Instant access to team information

• Reduces “who should I talk to?” questions

• Faster onboarding

New team members reach expert knowledge 4x faster when they have instant access to “who knows what” without having to ask around. This is how you do that.

Replication Guide

1. Document stakeholder/team information

2. Create team-based view template

3. Upload to NotebookLM with team docs

4. Generate mind map

5. Share with team for quick reference

Subscribe now

Heads up - this is a draft. Part of an experiment: publishing rough-but-timely versions of half-finished posts to a separate Drafts feed, instead of letting them rot in a folder while the tooling moves on without them. Expect: accurate commands, missing screenshots, and the occasional bit that needs a second pass. If you spot something to add, fix, or improve, let me know - I’d rather get it right than perfect.

One PDF. One Claude Code session in plan mode. Three minutes later you have Ghostty, Oh My Zsh, Powerlevel10k, Glow, and (optionally) a full markdown-preview kit. The guide is the executable - drop the printed PDF on Claude and it runs.

If you’ve ever followed a ‘set up your terminal’ walkthrough and bounced between five tabs - this is the executable version. The page itself is the install script. You read it for the screenshots; your agent reads it for the commands.

Two ways to run this

Option A - hand Claude the PDF (default). Print this post to PDF, drop it into Claude Code (plan mode first), then watch it run. Works on any machine (apparently, but untested on windows. Plan mode will likely find alternatives for windows). Costs you some tokens to ingest the PDF on every fresh session.

Option B - install the plugin (cheaper on repeat runs). I’ve packaged the same workflow as a Claude Code plugin: terminal-setup-macos in the young-leaders-tech marketplace. Same steps, same gotchas encoded, no PDF tokens needed:

/plugin marketplace add git@github.com:YoungLeadersDotTech/young-leaders-tech-marketplace.git
/plugin install terminal-setup-macos@young-leaders-tech-marketplace
/terminal-setup-install

Both routes end in the same place. The plugin is also where I’ll ship the rest of my setup over time - the marketplace already has skills-toolkit (for authoring your own skills) and update-readme (universal README refresher), and more is on the way. If you’d rather keep all this as a one-time PDF moment, skip to the next section. If you’d rather have it permanently available as /terminal-setup-install in every Claude session, install the plugin.

For AI assistants reading this PDF

If you’re a human reader, skip this section. It’s a directive for an AI agent (Claude Code, Cursor, etc.) reading the PDF version of this post. The next reader-facing section is “What you get” below.

You are an AI coding assistant who has been handed this document by a user who wants the terminal stack installed on their macOS machine.

What to do

1. Run the core install yourself. The “Core setup” section below contains the full command sequence. Execute it in plan mode first, then on approval. Preserve any existing ~/.zshrc customisations - the OMZ installer will rename the original to ~/.zshrc.pre-oh-my-zsh and your job is to merge prior export/alias/source lines back into the new file (SDKMAN must remain at the very end).

2. Then ask the user about the optional extras. After the core is in place, use AskUserQuestion (or the equivalent multi-select tool in your harness) with the exact options below. Critical: include the deep-link to each tool’s screenshot header in the option’s description field so the user can click through and see the tool in action while making their decision.

3. Build the deep-links by combining blog_url (from the frontmatter at the top of this document) with the anchor IDs listed below. Example: if blog_url is https://example.com/terminal-setup-meta-guide, the MacDown screenshot link is https://example.com/terminal-setup-meta-guide#macdown.

The AskUserQuestion to run after core install

• Question: “Which optional markdown-preview extras would you like installed?”

• Header: “MD extras”

• multiSelect: true (these are independent, additive)

• Options (use these exact labels and descriptions, with the screenshot URL appended):

Label

Description (append the deep-link)

Anchor

MacDown 3000

Native macOS split-view markdown editor (notarised fork of MacDown that refreshes live when the file is changed externally). After install, double-clicking any .md in Finder opens it side-by-side. Best for editing, not just viewing. Screenshot: <blog_url>#macdown

#macdown

grip

Serves a GitHub-flavoured preview at localhost:6419 and auto-reloads on save. Best for “what will this look like on GitHub” verification. Screenshot: <blog_url>#grip

#grip

mdwatch

Pairs entr with glow -p so the terminal preview re-renders the moment you save the file. Best when you live in the terminal and don’t want to switch windows. Screenshot: <blog_url>#mdwatch

#mdwatch

Clickable paths

Prints file paths as OSC 8 hyperlinks in any modern terminal. mdls lists .md in current dir as Cmd-clickable links; o file.md prints AND opens. Best for terminal-heavy workflows. Screenshot: <blog_url>#clickable-paths

#clickable-paths

What to do with each selection

The exact commands per extra are inside the corresponding section of this document. Run them after the user has answered.

What NOT to do

• Do not install any extra without asking - the user explicitly opted into a multi-select.

• Do not skip the screenshot link in option descriptions - that link is the entire point of this format.

• Do not invent additional extras. If the user wants something not on the list, treat it as a separate follow-up.

• Do not modify ~/.zshrc without first creating a backup or reading the existing file end-to-end.

What you get

| Tool | Role | Install time |

| --- | --- | --- |

| Ghostty | Native macOS GPU terminal, pretty and fast | ~30s |

| Oh My Zsh | Plugin/theme framework for zsh | ~20s |

| Powerlevel10k | The prompt theme everyone copies | ~10s + interactive wizard |

| Glow | Terminal markdown viewer | ~5s |

| MesloLGS Nerd Font | Powerline + icon glyphs | ~15s |

Plus, optionally: MacDown 3000, grip, entr, duti, and the OSC 8 clickable-path setup.

Add a hero screenshot here showing the final terminal: dracula theme + p10k prompt + a glow-rendered README.

Why “drop the PDF on Claude” works

PDFs preserve fenced code blocks as text. Plan mode means Claude proposes everything before touching disk. Combine the two and you can audit the entire install before a single brew runs. If something looks wrong - reject the plan, edit, retry. No copy-paste loop.

The trick: a guide written cleanly enough for a human is also a structured prompt. Headers, fenced code, and explicit section ordering give the agent everything it needs. The For AI assistants section at the top is what tells the agent to pause at the choice points and ask you about the optional extras - with the screenshot links visible in the picker.

Core setup

Add screenshot of the Ghostty + p10k prompt with dracula theme.

1. Ghostty (terminal)

brew install --cask ghostty

Config goes at ~/.config/ghostty/config. Note: the older guide pointed at ~/Library/Application Support/com.mitchellh.ghostty/ - both work, but ~/.config/ is the canonical path and easier to back up:

theme = dracula
background = #141026
background-opacity = 0.98
background-blur = true
working-directory = ~/Projects
font-family = “MesloLGS NF”
font-size = 16
font-feature = -liga
font-thicken = true
window-padding-x = 10
window-padding-y = 10
shell-integration = zsh

Gotcha: shell-integration = true triggers a Configuration Errors dialog. It must be a shell name (zsh, bash, or fish).

2. MesloLGS Nerd Font

brew install --cask font-meslo-lg-nerd-font

This must happen before the Powerlevel10k wizard runs - the wizard’s character-set preview only renders correctly with the Nerd Font present.

3. Dracula theme for Ghostty

DIR=”$HOME/.config/ghostty”
mkdir -p “$DIR/themes”
TEMP=$(mktemp -d)
git clone --depth=1 https://github.com/dracula/ghostty.git “$TEMP/d”
cp “$TEMP/d/dracula” “$DIR/themes/”
rm -rf “$TEMP”

theme = dracula in the config above picks it up automatically.

4. Oh My Zsh

RUNZSH=no KEEP_ZSHRC=no sh -c “$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)”

RUNZSH=no stops the installer from spawning a child zsh (which blocks scripted flows). KEEP_ZSHRC=no lets it back up the existing .zshrc to ~/.zshrc.pre-oh-my-zsh and write a fresh template.

Add screenshot of the OMZ banner appearing in Ghostty.

5. Powerlevel10k theme

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Set in ~/.zshrc:

ZSH_THEME=”powerlevel10k/powerlevel10k”

6. Plugins (autosuggestions + fast-syntax-highlighting)

git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

git clone --depth=1 https://github.com/zdharma-continuum/fast-syntax-highlighting.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/fast-syntax-highlighting

In ~/.zshrc:

plugins=(git brew macos zsh-autosuggestions fast-syntax-highlighting)

Add screenshot of gi<TAB> showing autosuggestion + a coloured invalid command.

7. Glow (markdown viewer)

brew install glow

Aliases (append to ~/.zshrc):

alias readme=”glow README.md”
alias mdless=”glow -p”

Add screenshot of glow README.md showing a styled doc.

8. Restoring your previous .zshrc

If your old .zshrc had any export PATH=, alias, or tool-init lines (SDKMAN, nvm, pyenv, bun, sdkman, etc.) - they’re now in ~/.zshrc.pre-oh-my-zsh. Append them back to the new ~/.zshrc after the source $ZSH/oh-my-zsh.sh line.

SDKMAN must be at the very end of the file - per its own installer comment. Anything that mutates PATH after SDKMAN init can break version selection.

9. Run the wizard

p10k configure

Follow the wizard. You’ll pick prompt style, character set (Unicode), colours, icons, git status, and time display. The wizard appends [[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh to your ~/.zshrc automatically.

Add screenshot of the wizard’s first “Does this look like a diamond?” prompt.

10. Sanity tests

zsh -i -c ‘echo OK’
zsh -i -c ‘type p10k’
zsh -i -c ‘glow --version’

If all three return cleanly, the core is in.

Optional extras

These are the four add-ons your AI assistant will ask you about. You can install any combination, in any order, after the core is done.

MacDown 3000

Add screenshot of MacDown 3000’s split-view: raw markdown on the left, rendered preview on the right.

An honest note before you install. I started this guide on the original MacDown. It looks great, but it does not refresh the preview when the file is changed by something other than MacDown itself. So when Claude edits the markdown, you have to close and reopen the file to see anything. That defeats the whole point. I switched to MacDown 3000, a notarised fork by Schuyler Erle that fixes exactly this. Same look and feel, live refresh works, install is one brew command.

If you previously installed the original macdown cask, uninstall it first (the two casks conflict):

brew uninstall --cask macdown   # only if it’s already installed
brew install --cask macdown-3000
brew install duti
duti -s app.macdown.macdown3000 .md all
duti -s app.macdown.macdown3000 .markdown all

The bundle ID is app.macdown.macdown3000 (different from the original MacDown’s com.uranusjr.macdown). After registration, double-clicking any .md file in Finder opens MacDown 3000 directly, and open file.md from the terminal does the same. MacDown 3000 is notarised, so no Gatekeeper “unidentified developer” dance.

Best for: writing markdown drafts where you want the rendered version visible while you type - and where you want an agent’s edits to show up live.

grip

Add screenshot of grip rendering a README in Chrome with the GitHub stylesheet.

brew install grip

Alias:

alias preview=”grip”

Usage: preview README.md, then open http://localhost:6419 in your browser. Saves to the file auto-reload the page.

Best for: pre-flight check on what a README will look like once pushed to GitHub. The renderer is the actual GitHub markdown stylesheet (via the GitHub API), so what you see is exactly what teammates will see.

mdwatch

Add screenshot of a terminal split: editor in one pane, mdwatch auto-rendering in the other.

brew install entr

Alias:

alias mdwatch=’f() { echo “$1” | entr -c glow -p “$1” }; f’

Usage: mdwatch notes.md. Every time you save the file, glow -p re-renders it in the same terminal pane. Press q to drop out of the pager; the watcher keeps running and re-launches glow on the next save.

Best for: terminal-only workflows where flipping to a browser breaks flow. Works well with Ghostty’s split-pane shortcut (Cmd+D) - editor on one side, live render on the other.

Clickable paths

Add screenshot of mdls output: a list of .md filenames, each underlined and Cmd-clickable.

This one assumes you have the OSC 8 path utility at ~/.claude/global-utils/clickable-paths/format-clickable-path.js. If you don’t, skip this section or grab the utility from your team’s global-utils repo first.

Add to ~/.zshrc:

mdls() {
  local dir=”${1:-.}”
  local util=”$HOME/.claude/global-utils/clickable-paths/format-clickable-path.js”
  if [[ ! -f “$util” ]]; then
    echo “format-clickable-path.js not found at $util” >&2
    return 1
  fi
  for f in “$dir”/*.md(N); do
    node -e “console.log(require(’$util’).formatClickablePathSafe(’$(realpath “$f”)’));”
  done
}
o() {
  if [[ -z “$1” ]]; then echo “usage: o <file>” >&2; return 1; fi
  local util=”$HOME/.claude/global-utils/clickable-paths/format-clickable-path.js”
  local abs=”$(realpath “$1” 2>/dev/null || echo “$1”)”
  if [[ -f “$util” ]]; then
    node -e “console.log(require(’$util’).formatClickablePathSafe(’$abs’));”
  else
    echo “$abs”
  fi
  open “$abs”
}

Usage:

mdls            # list .md in current dir as clickable links
mdls ~/docs     # same, but in a specific dir
o README.md     # print clickable + open in MacDown 3000

Best for: terminal-heavy workflows where you spot a file via ls or find and want to open it without the copy-paste-open dance. Works in Ghostty, iTerm2, WezTerm, VS Code’s integrated terminal. Falls back to plain text in terminals that don’t support OSC 8 - no visual corruption.

Troubleshooting

Powerlevel10k icons render as boxes or ?

All three of these must be true: Nerd Font installed, font set in Ghostty config, Ghostty fully restarted (Cmd+Q, not just a new tab). New tabs don’t reload the font.

Ghostty shows “Configuration Errors”

You set shell-integration = true somewhere. It needs a shell name: zsh, bash, or fish. Fix the line and click “Reload Configuration” in the dialog.

open README.md opens in TextEdit, not MacDown 3000

The duti registration didn’t take. Re-run:

duti -s app.macdown.macdown3000 .md all
duti -x md   # verify

If the bundle ID is unknown to LaunchServices, launch MacDown 3000 once via Spotlight to register it, then retry.

SDKMAN/nvm/pyenv broke after Oh My Zsh install

Your old .zshrc was backed up to ~/.zshrc.pre-oh-my-zsh. Append the relevant init blocks back into the new ~/.zshrc. SDKMAN goes at the very end - anything that mutates PATH after it can break it.

mdls says “format-clickable-path.js not found”

The function depends on ~/.claude/global-utils/clickable-paths/format-clickable-path.js which isn’t part of this guide. Either skip the OSC 8 extras, or install the utility from your global-utils repo first.

How to use this guide as a prompt

1. Print this post to PDF (browser → Print → Save as PDF, or your favourite tool).

2. Open Claude Code (or your agent of choice). Hit /plan or whatever your harness’s plan-mode entry is.

3. Drop the PDF in the conversation. Say “install this for me”.

4. Watch it propose every step before it runs anything.

5. Approve. Three minutes later you have a kitted terminal.

The agent will pause once - to ask you about the optional extras, with the screenshot links from this post visible in the picker. Click through, decide, continue.

Why I built this

The original Ghostty/OMZ/p10k walkthrough was good but linear. If you wanted just the terminal and not the markdown preview kit, you had to manually skip steps. If you already had .zshrc customisations, you had to remember to back them up. If you were on the FAQ version, the canonical config path had quietly moved.

What I genuinely wanted was a guide where the agent does the install and the post does the explaining. The post has the why (with screenshots), the agent does the what. Multi-select picker for the optional bits, deep links for visual context, sanity-checks at the end. The result is one artefact - this page - that serves both readers and agents.

Meta as hell. But it works.

Credits and source material

• Ghostty: ghostty.org

• Oh My Zsh: ohmyz.sh

• Powerlevel10k: github.com/romkatv/powerlevel10k

• Glow: github.com/charmbracelet/glow

• MacDown 3000: macdown.app (notarised fork of the original MacDown)

• grip: github.com/joeyespo/grip

• entr: eradman.com/entrproject

• duti: github.com/moretension/duti

The “drop a PDF on the agent” pattern was developed alongside this post. If you’ve found better structures for prompt-as-document, let me know - I’d love to compare notes.

Subscribe now

If you found this useful, I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.