Getting Started

Set up Clark in a few minutes and learn the basics of Socratic tutoring from the desktop app.

Step 1

Install Clark

Download the latest macOS desktop build from GitHub Releases.

Download for macOS

Open the downloaded DMG, drag Clark into your Applications folder, and launch it. Current desktop releases are unsigned beta builds, so macOS may show a security prompt on first launch.

macOS Quarantine: If macOS blocks the app with "cannot be opened because the developer cannot be verified", run this command in Terminal then relaunch:
$ xattr -d com.apple.quarantine /Applications/Clark.app
This is expected for unsigned builds during early development.
Tip: Keep the CLI workflow if you prefer terminal usage: curl -fsSL https://raw.githubusercontent.com/alexracape/clark/main/install.sh | bash.
Step 2

Understanding Your Workspace

Clark organizes your work into a simple folder structure. If you start in an empty directory, Clark creates: 

                    ~/Library/
                    ├── Notes/ # Your markdown notes
                    ├── Resources/
                    │   ├── PDFs/ # Course materials
                    │   ├── Images/ # Diagrams, screenshots
                    ├── Templates/ # Note templates
                    └── Clark/
                        ├── CLARK.md # Custom instructions
                        ├── Canvas/ # tldraw files
                        └── Transcripts/ # OCR'd PDFs
                        └── Structures/ # Reusable templates

If you already have notes, they stay exactly where they are. Clark just adds the Clark/ folder for its configuration and canvas files.

Tip: Clark automatically reads markdown files in your workspace. For best results, organize notes by linking them together with [[wikilinks]].
Step 3

Choose a Provider

On first launch, Clark will guide you through picking an LLM provider. You'll need an API key from one of the following:

  • Anthropic Claude models — get a key at console.anthropic.com
  • OpenAI GPT-4o models — get a key at platform.openai.com
  • Google Gemini models — get a key at aistudio.google.com
  • Ollama Run models locally — no API key needed (setup guide)

Your API key is saved securely in macOS Keychain. You can also set it as an environment variable (e.g. ANTHROPIC_API_KEY) to override.

Tip: You can switch providers anytime with the /model command.
Step 4

Asking Questions

Type your question in the input field and press Enter. Clark responds with guiding questions to help you think through the concept, rather than giving you the answer directly.

you What is recursion?

clark Good question! Have you ever seen a function
that calls itself? What do you think would
happen if it kept going forever?
Tip: The more specific your question, the better Clark can help. Instead of "explain sorting", try "why is my bubble sort returning duplicates?"
Step 5

Slash Commands

Clark supports a set of slash commands for quick actions. Type / and press Tab to see suggestions.

  • /help See all available commands
  • /model Switch between LLM models and providers
  • /canvas Open a drawing board (great for iPad)
  • /export Save your canvas as a PDF
  • /context Check your current context usage
  • /feedback Send feedback so we can improve
  • /clear Start a fresh conversation
Step 6

Adding Context

You can share files with Clark by pasting paths directly into your messages. Clark will read the file and use it as context for the conversation.

you Can you explain this code? ~/homework/sort.py

Clark can read and understand:

  • .py
  • .js
  • .java
  • .c
  • .pdf
  • .png
  • .jpg
  • .md

Clark also automatically reads markdown files in your workspace directory. Your class notes, problem sets, and study guides become part of the conversation without any extra steps.

PDF Processing: For enhanced PDF support with visual analysis of diagrams and equations, install Poppler. See the dependencies setup guide for installation instructions.
Tip: Drag and drop files into your terminal to paste their path automatically.
Step 7

Canvas and Handwriting

Clark includes a tldraw canvas that you can open on your iPad. Write, sketch, and diagram with Apple Pencil while Clark sees your work in real time.

  1. Type /canvas to create or open a canvas
  2. Open the URL on your iPad's browser
  3. Start drawing, writing, or diagramming with Apple Pencil
  4. Clark can see your canvas and respond to your work

The canvas is perfect for:

  • Working through math problems step by step
  • Sketching diagrams and flowcharts
  • Handwritten notes and brainstorming
  • Drawing data structures and algorithms
Tip: Use /export to save your canvas as a PDF when you're done.
Advanced

Customization & Advanced Features

Once you're comfortable with the basics, explore these customization options:

Customize with CLARK.md

The Clark/CLARK.md file lets you add custom instructions specific to your workspace. Tell Clark about your course, learning goals, or preferred teaching style.

# Clark/CLARK.md I'm taking CS229 (Machine Learning) taught by Andrew Ng. Focus on intuition over equations. When I ask about algorithms, help me understand the "why" before the "how".

Create Structure Templates

Structure files in Clark/Structures/ define reusable templates for common note types. Clark comes with templates for Papers, Classes, Problem Sets, and more.

You can edit existing structures or create your own. Each structure file defines how Clark should help you create that type of note.

# Example: Ask Clark to create a new Paper structure you Create a paper for "Attention Is All You Need" clark I'll create a Paper structure for that. What's the main idea you want to capture?

Organize Your Notes

Clark reads all markdown files in your workspace automatically. For best results:

  • Use subdirectories to organize notes by topic or week
  • Use wikilinks [[like this]] to reference other notes
  • Keep course materials in Resources/PDFs/
  • Drop PDFs into the terminal to auto-transcribe them

Use Obsidian for Note Management

Since Clark stores everything as plain markdown files, you can use Obsidian to view, edit, and organize your notes with a rich visual interface. Obsidian's graph view, powerful search, and plugin ecosystem work seamlessly with Clark's workspace structure.

Learn more in the dependencies setup guide.

Tip: Type /feedback <message> anytime to send suggestions or report issues. Your feedback helps us improve Clark.
Ready to go

Start Learning

You now know everything you need to get started with Clark. Open the desktop app, select your workspace, and start chatting.

Remember: use /help anytime to see available commands, or /tutorial to replay the walkthrough.

Need more help?

  • Check out the GitHub repository for detailed documentation
  • Use /feedback to send suggestions or report issues
  • Browse Clark/Structures/ for examples of custom templates