Specialization 1: Your AI-Native Workspace

Your files, your agent — set up a workspace where AI lives alongside your projects, notes, and documents.

INFO

• Time: ~3-4 hours
• Difficulty: Beginner
• Prerequisites: Core Modules completed

---

This Page Covers

• Why workspace agents are fundamentally different from chat UIs
• Setting up VS Code as your AI-native workspace
• Working with agents that read and write your files directly
• Building a knowledge environment in plain Markdown
• Using Git as memory for your workspace
• When to use which tool

---

The Opposed Forces: Web UIs vs. Workspace Agents

There are two fundamentally different ways to work with AI. Most people only know the first one.

The Web UI Model (ChatGPT, Claude.ai)

You open a browser. You type a question. If you need AI to work with your files, you are the courier:

1. Find the file on your computer
2. Copy-paste or upload it into the chat
3. Wait for AI to respond
4. Copy the response back to your file
5. Repeat for every file, every conversation

This works for quick questions. But for anything involving your actual files and projects, you spend more time shuttling data between your computer and the chat window than doing real work.

The bottleneck is you. AI cannot see your files. It cannot read your project. It cannot check related documents for context. It only knows what you paste in, right now, in this conversation.

The Workspace Agent Model (Claude Code, Codex)

Now imagine something different. AI lives in your editor. It can see your files. When you ask a question about your project, the agent reads the relevant files itself. When you ask it to create something, it writes the file directly. When you ask it to reorganize your notes, it does it — across dozens of files at once.

The loop changes:

1. You give an instruction
2. The agent reads whatever context it needs
3. The agent produces the result
4. You review and approve

You go from courier to director. Instead of manually feeding AI one piece of context at a time, you point it at your workspace and let it figure out what it needs.

Side-by-Side Comparison

Task	Web UI approach	Workspace agent approach
Summarize a long document	Copy-paste the document into chat	"Summarize reports/Q4-review.md"
Find info across your notes	Open files one by one, paste each	"Search my notes for anything about marketing strategy"
Create a new document from context	Paste 3-4 reference docs manually	"Create a project brief based on the files in projects/website-redesign/"
Reorganize a folder of notes	Move files manually, ask AI for suggestions one at a time	"Organize the files in inbox/ into the right project folders"
Refactor a project	Paste each file, track changes yourself	"Rename the utils references across all files in src/"

This difference is not incremental. It changes what you use AI for.

---

Setting Up Your AI-Native Workspace

Install VS Code

If you do not already have it:

1. Go to code.visualstudio.com
2. Download and install for your operating system
3. Open it and get comfortable with the basics

VS Code is the hub — not because it is the best text editor, but because it is where agents can live alongside your files.

Install Claude Code (or Codex)

Claude Code runs in your terminal, inside your project. It can see all the files in your workspace.

Claude Code:

1. Open your terminal
2. Run: npm install -g @anthropic-ai/claude-code
3. Run claude in any project folder to start
4. Claude Code can now read and write files in that folder

Alternative — OpenAI Codex: If you prefer OpenAI's ecosystem, Codex offers a similar workspace agent experience. The principles in this specialization apply to both.

Which agent to use

Claude Code and Codex are the most capable workspace agents today. The workflows in this specialization work with either. Pick the one you have access to.

Recommended VS Code Extensions

These extensions make your workspace more AI-friendly:

• Foam — Adds wiki-style [[double bracket]] linking between Markdown files. Your agent can follow these links to understand how your notes connect.
• GitLens — Shows who changed what and when, directly in your editor. Useful when you ask the agent about file history.
• Markdown All in One — Better Markdown editing: shortcuts, table formatting, auto-preview.

Install them from the VS Code Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).

Workspace Folder Structure

Keep it simple. The agent is your organizer — you do not need an elaborate system upfront.

my-workspace/
├── inbox/          ← New captures, unsorted
├── projects/       ← Active work
├── reference/      ← Things you look up
└── archive/        ← Done or inactive

Create this structure in a folder on your computer. Open it in VS Code with File → Open Folder. This is now your workspace.

---

Working With Agents in Your Files

Once your workspace is open and your agent is running, the core loop is:

You instruct → Agent reads → Agent produces → You review

Here are the workflows that matter.

Ask About Your Files

The simplest starting point. Instead of opening and reading files yourself, ask:

• "What files are in the projects/ folder?"
• "Summarize reference/api-notes.md"
• "What did I write about deployment in my notes?"

The agent reads the files and responds. No copy-pasting needed.

Create From Context

This is where workspace agents pull ahead. Instead of providing context manually, the agent gathers it:

• "Write a project brief for the website redesign based on the meeting notes in projects/website-redesign/"
• "Create a README for this project based on the existing code and comments"
• "Draft an email summarizing the key points from reports/Q4-review.md"

The agent reads the relevant files, synthesizes, and writes the result.

Refactor and Organize

Agents can work across many files at once:

• "Rename all references to oldName to newName across the project"
• "Move the notes in inbox/ to the appropriate project folders based on their content"
• "Find all TODO comments in this project and list them"

Generate From Templates

If you have a consistent format for something (meeting notes, project briefs, weekly reviews), create a template file and let the agent use it:

• "Create a new meeting note using the template in templates/meeting.md for today's standup"
• "Generate a weekly review for this week based on templates/weekly-review.md and my daily notes"

The Review Step Matters

The agent writes files, but you approve. Get in the habit of reviewing what changed:

• Read the output before committing
• Use git diff to see exactly what the agent modified
• If something is wrong, tell the agent — it can see its own changes and fix them

---

Building a Knowledge Environment

A knowledge system does not need special software. It needs a folder of Markdown files and an agent that can work with them.

Why Markdown?

Markdown (.md files) is the format AI agents work with best:

• Plain text — any tool can read it, forever
• Structured — headings, lists, and links give the agent something to parse
• Lightweight — no proprietary format, no app lock-in
• Git-friendly — every change is trackable

Your notes, project docs, reference material, meeting minutes — all of it works as Markdown files in folders.

The Folder Structure

knowledge/
├── inbox/          ← Quick captures, process later
├── projects/       ← Active project notes and docs
├── reference/      ← How-tos, snippets, resources
└── archive/        ← Completed or inactive

This is the same structure from earlier. Keep it flat — avoid deep nesting. Search beats folders. When you need to find something, use VS Code's search (Ctrl+Shift+F / Cmd+Shift+F) or ask the agent. Two levels of folders is usually enough.

Wiki-Linking With Foam

Install the Foam extension for VS Code. It adds support for [[double bracket]] links between your Markdown files:

## Meeting Notes - March 15

Discussed the [[website-redesign]] timeline with the team.
Key concern: [[deployment-strategy]] needs to be finalized before launch.
See also: [[Q1-goals]] for context on priorities.

These links create connections between notes. More importantly, the agent can follow them. When you ask "What relates to the website redesign?", the agent can trace the links and find connected documents.

Foam also gives you a graph view of all your linked notes — useful for spotting isolated notes that should connect to something.

Agent as Librarian

Once you have notes accumulating, the agent becomes your librarian:

• Find orphans: "Which notes in my knowledge folder have no links to other notes?"
• Suggest connections: "Read my recent notes and suggest which ones should link to each other"
• Identify stale content: "Which notes haven't been updated in over 6 months?"
• Summarize a topic: "What do my notes say about marketing? Pull from all relevant files."
• Process inbox: "Review the files in inbox/ and suggest which folder each belongs in"

This is the compound value of a knowledge system: the more notes you add, the more the agent can do with them.

Write for Your Future Self

When you write a note, imagine reading it six months from now. Add enough context that future-you (and the agent) can understand what you meant:

• Use clear, descriptive headings
• State the "why" — not just the "what"
• Include dates for time-sensitive information
• Link to related notes

A note titled ideas.md with bullet points is less useful than 2024-03-15-website-redesign-ideas.md with context about what prompted the ideas and which project they relate to.

---

Git as Memory

You learned Git in Module 7. Here, we apply those same commands specifically to your knowledge base — using version control not for code, but for your notes and documents.

Your notes folder should be a Git repository. This gives you and the agent a complete history of every change.

Setting It Up

cd ~/knowledge
git init
git add .
git commit -m "Initial knowledge base"

From now on, commit periodically — daily is a good rhythm. The agent can help:

• "Commit my changes with a descriptive message"
• "What did I change in my notes this week?" (reads git log)
• "Show me the history of projects/website-redesign.md"

Why Git History Matters

Git turns your notes into a timeline. The agent can read this timeline:

• Track your thinking: "How has my understanding of this topic evolved?"
• Recover lost work: "What was in notes/api-design.md before I rewrote it last Tuesday?"
• Weekly reviews: "Summarize the changes I made to my knowledge base this week"

You do not need to push to GitHub (though you can for backup). A local Git repo is enough.

---

When to Use What

Your AI-native workspace is not the only tool. Here is when to use each:

Situation	Best tool
File-heavy, context-rich work	VS Code + workspace agent — agent sees all files
Quick one-off question	Web UI (Claude.ai, ChatGPT) — no setup needed
Mobile or on the go	Web UI or mobile app — VS Code is desktop
Brainstorming, open-ended chat	Web UI — conversation-first interface
Connecting to external systems (APIs, SaaS tools)	Claude Desktop + MCP (→ Specialization 2)
Automating web tasks	Playwright MCP (→ Specialization 3)

The workspace agent is your default for anything that touches your files. The web UI is your fallback for everything else.

---

Mini Project: Set Up Your AI-Native Workspace

Goal

By the end of this project, you will have a working AI-native workspace with notes, links between them, and an agent that can navigate and work with your knowledge base.

Steps

1. Create your workspace folder

Create a folder structure:

knowledge/
├── inbox/
├── projects/
├── reference/
└── archive/

Initialize it as a Git repo: git init

2. Install your tools

• Open the folder in VS Code
• Install Foam, GitLens, and Markdown All in One extensions
• Install Claude Code (or your preferred workspace agent)

3. Create 5-10 notes

Write real notes — not test data. Ideas:

• A note about a current project
• A summary of something you recently learned
• A how-to for something you do regularly
• A note about a decision you made and why
• Meeting notes or a journal entry

Use [[double bracket]] links between notes where topics connect.

4. Ask the agent to work with your notes

Run your agent in the workspace folder and try:

• "Summarize what's in my knowledge base"
• "Which notes relate to each other but aren't linked?"
• "Create a new note that connects the themes across my project notes"
• "What topics am I writing about most?"

5. Commit and review

git add .
git commit -m "First week of knowledge base"

Ask the agent: "Summarize the git history of my knowledge base."

What You Have Built

• A workspace where AI agents can read and write your files directly
• A knowledge base in plain Markdown with wiki-links between notes
• Git history tracking every change
• Experience directing an agent instead of manually shuttling data

---

Key Takeaways

• Workspace agents (Claude Code, Codex) fundamentally change how you use AI — the agent lives in your files, not behind a web form
• VS Code is the hub because agents can operate inside it, not because it is the best editor
• Plain Markdown files in folders are the ideal format for both you and the agent
• Search beats folders — keep your structure flat, let the agent find things
• Git gives your workspace a memory that the agent can read
• The core loop is: instruct → agent reads → agent produces → you review
• Start simple (a folder, a few notes, an agent) and let complexity emerge from use

---

Next Steps

• Specialization 2: Connect AI to Your Systems (MCP) — Give your agent access to external tools and APIs, not just local files
• Specialization 3: Agentic Browser Automation — Have your agent control a browser to automate web tasks