4 Positron

In Your First R Project, you used Positron to run a single-cell analysis, write code in the editor, execute it in the console, inspect objects in the variables pane, and view plots in the plotting window. This chapter digs deeper into how Positron is set up and how you can effectively use it in your projects. In going deeper, it covers what all those panels actually are, how to manage multiple sessions, and the habits that make daily work smoother.

It was only a couple months ago that I personally made the switch over from RSTudio to Positron. It has quickly become my favorite IDE (Integrated Developer Environment). It’s where I write code, explore data, run analyses, and manage my ongoing data science projects. Built by Posit, the company behind RStudio, Positron combines many of the best features of Rstudio, including its plotting windows and environment manager, with the best features of VS Code, especially how easy it is to manage and explore project files, work with git and github, and employ extensions like Claude Code that integrates seamlessly into projects.

4.1 Why Positron?

If you’re coming from RStudio like me, Positron will feel familiar in at least some ways. As in RStudio, there’s an R console, a variable explorer, a data viewer, and a file browser. Conversely, if you’ve used VS Code before, Positron will feel very familiar, but with added data science features. A few features that I find most useful are:

Full support for both R and Python. It is increasingly the case that our data science projects rely on both language. Although Seurat and many classic bulk RNA-seq pipelines were established in R, there are a growing number of essential python tools, including packages for single-cell analysis like Scanpy and metacell. Whereas in the past R led data science software with packages like tidyverse, the python toolkit has largely caught up. Combined with its flexibility for manipulating strings and files, and its readable, intuitive syntax, python is quickly becoming an essential language for computational biologists. Fortunately, in Positron you can have R and Python sessions running side by side, each with its own console and environment viewer. In practice I usually write one language per script (.qmd file), but I now routinely use both languages within a project, and sometimes even at the same time, running a script in one console while tinkering in another. In Positron, it’s easy to switch between them, with the console, environment viewer, and plotting pane updating to reflect session you’re working with at the moment.

A superior Data Viewer. One of my favorite things about Positron is the interactive Data Viewer, which works with both R and Python objects in your environment (for example, tibbles and pandas DataFrames), as well as TSV and CSV files in the file explorer. Click any data object in the Variables pane and it opens in a fast, interactive viewer. You can sort columns, filter rows, and search for values. For text files, you can also use grep-style search for more sophisticated find and replace operations. Most usefully, for large datasets it can smoothly handle millions of rows, and it summarizes each column, giving you a histogram and basic stats like the number of missing values. The ability to quickly open the Data Viewer is central to exploratory analysis, and you should routinely take advantage of it.

Access to VS Code extensions. Positron inherits access to thousands of extensions, most notably Claude Code and Codex, the two main coding assistants on the market from Anthropic and OpenAI, respectively. This is a major difference from RStudio, which has relatively few extensions and cannot really interact with agentic AI.

4.1.1 RStudio → Positron Translation

If you’re coming from RStudio, here are a few key differences you’ll notice:

RStudio concept	Positron concept	What changes?
“Project” (.Rproj)	Open Folder / Workspace	The folder is the project, and when opened it operates as a workspace.
R console	R console	Still an R process, but integrated with a broader editor/terminal model.
Python integration	Python interpreter	You choose which Python environment to use for each project.
“Environment pane”	variable viewers + terminal + notebooks	Different UI, same goals.

[TODO: screenshot of Positron interface with labeled panes]

4.2 The Bottom Panel: Console, Terminal, and Variables

The bottom of the Positron window is where most of the interactive work happens. It contains tabs for your language consoles and system terminals. It is important to understand what each of these is and when to use them.

4.2.1 Console vs Terminal

These are the two most important tabs in the bottom panel, and they do fundamentally different things.

The Console is your R or Python session. When you press Cmd+Enter (macOS) or Ctrl+Enter (Windows) to run code chunk in a .qmd file, it executes here. This is where you see R output, error messages, and package loading messages. In Your First R Project, every time you ran a code chunk, the results appeared in the Console.

The Terminal is a system shell, the same thing as Terminal.app on macOS or PowerShell on Windows, but built into Positron. It opens automatically at the top level of your project folder, so you’re always in the right place to run commands. You can use it for any bash or shell commands, including moving around and manipulating files, running git, activating conda environments, rendering Quarto documents, or anything else you’d normally do at a command line. Some of these tasks can also be done through Positron’s GUI (like Git through the Source Control panel), but the terminal is always available as a fallback or when more control is needed.

The key distinction is where commands run: R and Python code goes in the Console, shell commands go in the Terminal. If Claude Code tells you to run conda activate my-project, that goes in the Terminal. If it tells you to run library(Seurat), that goes in the Console.

Mixing them up is an easy mistake and a common source of confusion. You’ll usually notice quickly. You’ll get an “! object not found” message if you type a shell command into the R console, or “command not found” if you type R code into the terminal.

Windows Users: Terminal Differences

On macOS, the integrated terminal runs a Unix shell (zsh or bash). On Windows, it runs PowerShell by default. Most commands in this book work the same way, but a few common differences trip people up:

Directory listing: ls works in both, but PowerShell’s ls is an alias for Get-ChildItem and behaves slightly differently
File paths: Use backslashes (\) in PowerShell, or forward slashes (/) which also work in most contexts
Conda activation: If conda activate doesn’t work, you may need to run conda init powershell first and restart (see the Conda chapter)

When in doubt, commands shown in this book with default code blocks work on both platforms unless otherwise noted.

[TODO: screenshot showing Console and Terminal tabs in the bottom panel]

4.2.2 Managing Multiple Sessions

As you work, the bottom panel accumulates tabs. You might have an R console, a Python console, and two or three terminals open at once. Each appears as a labeled tab — “R”, “Python”, “Terminal”, “zsh”, and so on. Click a tab to switch to that session.

The + button in the bottom panel creates new terminals. Language consoles appear when you start a session — either by running code in a .qmd file or by clicking “Start R Session” (or “Start Python Session”) in the status bar.

You can have multiple R sessions open at the same time. This is occasionally useful — for example, if you want to keep one session with a large dataset loaded while experimenting in another. But be careful: whichever console is currently visible is where Cmd+Enter sends your code. If you have two R sessions and you’re looking at the wrong one, your code runs in a session that might not have the objects you expect. When something seems inexplicably broken, check which console tab is active.

[TODO: screenshot showing multiple tabs in the bottom panel — R console, Terminal, etc.]

4.2.3 The Variables Pane

The Variables pane shows every object in your current R or Python session — dataframes with their row and column counts, vectors, lists, models, and other objects. You used this constantly in Your First R Project to keep track of what was in memory.

Click any dataframe to open it in the Data Viewer (more on that below). For other objects, you can expand them to see their contents. The Variables pane updates in real time as you create, modify, or remove objects.

When you switch between R and Python consoles, the Variables pane switches too — it always shows the objects for whichever console is currently active.

4.3 The Data Viewer

The Data Viewer is one of Positron’s standout features and something you’ll use every day. In Your First R Project, you opened it with View(sponge@meta.data) to inspect cell metadata in a spreadsheet-like view. Here’s what it can do.

There are two ways to open the Data Viewer. You can click any dataframe in the Variables pane — this is what you did in Your First R Project with View(sponge@meta.data). You can also click a data file (like .csv or .tsv) directly in the File Explorer, and Positron will open it in the Data Viewer rather than as a text file. This is a quick way to peek at data files without loading them into R or Python first.

Once open, the Data Viewer shows your data in a fast, interactive table where you can:

Sort by clicking column headers
Filter rows using the filter bar — type conditions to narrow down the data
Search for specific values across the table
See distributions via the small column histograms at the top of each numeric column

During exploratory analysis, you’ll have the Data Viewer open constantly — checking data after each transformation, looking for unexpected values, verifying that joins worked correctly.

Seurat Objects

You can’t view a Seurat object directly in the Data Viewer — it’s a complex nested structure, not a simple dataframe. To inspect the metadata, use View(sponge@meta.data) in the console. This opens just the metadata table, which is what you usually want to see.

[TODO: screenshot of Data Viewer with filtering active and column histograms visible]

4.4 Navigating Your Project

4.4.1 The File Explorer and Outline

The File Explorer in the left sidebar shows all files and folders in your project — specifically, the top-level folder you opened as your workspace. It only shows what’s inside that folder, which keeps things focused on your project. Click files to open them (data files like .csv and .tsv open in the Data Viewer; code files open in the editor). To create new files or folders, click the new file or new folder icons (the small buttons with a + symbol) at the top of the Explorer panel, or right-click for more options (rename, delete, etc.).

Below the file list (or in a separate section of the sidebar), the Outline panel shows the structure of the current document. For .qmd files, it lists headings and code chunks. For R or Python scripts, it shows function definitions. Click any item to jump directly to that section. When your analysis scripts get longer — and they will — the Outline becomes essential for navigating without endless scrolling.

[TODO: screenshot showing the Outline panel for a .qmd file with headings and code chunks]

4.4.2 Opening Files Quickly

Once your project has more than a few files, clicking through the File Explorer gets slow. Press Cmd+P (macOS) or Ctrl+P (Windows) to open the Quick Open bar — start typing part of a filename and Positron shows matching files. Hit Enter to open one. This is much faster than navigating through folders, especially when you know the filename you want.

4.4.3 Working with Multiple Files

Files open as tabs in the editor area. You can have many files open at once and switch between them by clicking tabs.

For side-by-side viewing, drag a tab to the right edge of the editor — it splits the view so you can see two files at once. This is useful when you’re reading one script’s outputs while writing code that depends on them, or comparing two versions of an analysis.

4.5 Search

Press Cmd+Shift+F (macOS) or Ctrl+Shift+F (Windows) to open project-wide search. Type a term and Positron searches every file in your project, showing results grouped by file with the matching lines highlighted.

This is useful for finding where a function is defined, locating every use of a variable name, or searching for a specific value across your project. Click the .* button next to the search bar to enable regular expressions for more powerful pattern matching.

4.6 The Command Palette

The Command Palette is Positron’s universal command search. Open it with Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows), then start typing what you want to do. It searches through every available command — from switching R versions to changing color themes to toggling panels.

You’ll most often encounter the Command Palette when Claude Code tells you to use it. For example, Claude might say “open the Command Palette and type ‘Python: Select Interpreter’ to choose your conda environment.” Rather than memorizing where every setting lives in menus, you type what you’re looking for and the Command Palette finds it.

It’s also how you discover features you didn’t know existed. Not sure if Positron can do something? Open the Command Palette and start typing — you might be surprised.

[TODO: screenshot of the Command Palette with a search term entered]

4.7 The Status Bar

The status bar runs along the very bottom of the Positron window. It’s easy to overlook, but it contains useful information at a glance:

Active R version (e.g., “R 4.4.2”) — click to change
Python interpreter (e.g., “Python 3.11 (my-project)”) — click to change
Current Git branch (e.g., “main”)
Line and column number for your cursor position

When something isn’t working — code behaves unexpectedly, packages seem missing, or a render fails — check the status bar first. It often reveals the problem immediately: you’re running the wrong R version, or your Python is pointing at the base conda environment instead of your project environment.

[TODO: screenshot of the status bar, annotated to show R version, Python interpreter, Git branch, and line/column]

4.8 Essential Keyboard Shortcuts

You don’t need many shortcuts to be productive. These are the ones that matter:

Action	macOS	Windows
Run current line/selection	Cmd+Enter	Ctrl+Enter
Run current chunk	Cmd+Shift+Enter	Ctrl+Shift+Enter
Open Command Palette	Cmd+Shift+P	Ctrl+Shift+P
Quick file open	Cmd+P	Ctrl+P
Toggle terminal	Cmd+`\| Ctrl+`
Save file	Cmd+S	Ctrl+S

The most important is Cmd+Enter (or Ctrl+Enter) — you’ll use it constantly to run code. The Command Palette (Cmd+Shift+P) is how you access any command in Positron; if you’re not sure how to do something, open the Command Palette and start typing.

Just These Shortcuts

Some people learn dozens of keyboard shortcuts. That’s fine, but not necessary. The shortcuts above cover 90% of what you need. Add more only if you find yourself doing something repeatedly.

4.9 Working with R

4.9.1 Starting and Restarting R

An R session starts automatically when you run R code from a .qmd file or click “Start R Session” in the status bar. If the project has renv set up, you’ll see a message like Project loaded. [renv 1.0.0] confirming that project-specific packages are active.

Restarting R is something you’ll do regularly. Click the power icon (↻) in the Console toolbar, or press Cmd+Shift+0 (macOS) / Ctrl+Shift+0 (Windows). This kills the current R process and starts a fresh one.

Why would you restart? During interactive development, your R session accumulates objects — dataframes, models, intermediate results. Some of these might not be created by your script; you might have defined them manually in the console while experimenting. Over time, the environment gets cluttered and it becomes hard to tell what’s in your script versus what you created on the fly. Restarting gives you a clean slate.

This is also how you test whether your script is self-contained. After restarting, run your script from the top: if everything executes cleanly, your script has all the code it needs. If it fails — usually with “object not found” errors — you know something was missing from the script. This is the same test that rendering performs (rendering always starts from a fresh session), but restarting lets you catch problems interactively before you wait for a full render.

Claude Code

Claude Code can help diagnose the common “works interactively, fails on render” problem by checking what’s in your script versus what’s in your session.

My .qmd renders fine when I run chunks interactively, but quarto render fails with “object ‘filtered_data’ not found”. I think I have all the code in the script. Can you check what’s missing?

Claude will read your script, trace where filtered_data should be created, and identify the gap — often a line you ran in the console but forgot to include in a chunk.

4.9.2 Setting the R Version

If you have multiple R versions installed (via rig), you can choose which one Positron uses for a project:

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Type “R: Select R Binary”
Choose the version you want

This usually only needs to be done once per project — Positron remembers your choice and uses it every time you open the project. If you later use the Musser Lab’s /new-project skill in Claude Code (covered in Part 3), it sets the R version automatically when setting up a new project.

See the R: rig & renv chapter for more on managing R versions and packages.

4.10 Working with Python

4.10.1 Selecting an Interpreter

When you first open a project that uses Python, you need to tell Positron which conda environment to use:

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Type “Python: Select Interpreter”
Choose your project’s conda environment from the list

Like R, this only needs to be done once per project — Positron remembers your choice. If you later use the Musser Lab’s /new-project skill in Claude Code (covered in Part 3), it configures this automatically.

See the Conda chapter for how to create and manage Python environments.

Environment Not Showing?

If you just created a new conda environment, you may need to restart Positron for it to detect the new environment. This is a common gotcha — restart and try again.

Claude Code

Claude Code can troubleshoot Positron configuration issues like missing interpreters, environment detection, and extension problems.

Positron isn’t finding my conda environment “my-project”. When I open the interpreter selector, it’s not in the list. I created it with conda create -n my-project python=3.11 and it shows up when I run conda env list in the terminal. What should I check?

Claude will check your conda installation path, Positron’s Python discovery settings, and suggest fixes — typically a configuration change or a Positron reload.

4.10.2 Automatic Environment Switching

One of Positron’s strengths: when you switch between projects, environments switch automatically. If Project A uses conda-env-a and Project B uses conda-env-b, opening each project activates the correct environment without manual intervention.

4.11 Source Control Basics

Understanding Git basics in Positron is important, even if you later use Claude Code for most commits. The Source Control panel (click the branch icon in the left sidebar, or Cmd+Shift+G / Ctrl+Shift+G) shows which files have changed since your last commit.

The basic workflow:

Make changes to your files
Open Source Control panel — review changed files (click a file to see the diff)
Stage files by clicking the + icon next to each file
Type a commit message in the text box
Click the checkmark to commit
Push to GitHub via the three-dot menu (⋯) → Push

Claude Code and Git

Once you’re comfortable with Git basics, you may use Claude Code to handle commits. The /done command commits your work and can publish Quarto books. But understanding what’s happening in the Source Control panel helps you verify that commits are correct and troubleshoot when things go wrong.

See the Git & GitHub chapter for a full introduction to version control.

4.12 When Things Go Wrong

Things will go wrong — a panel will disappear, an interpreter won’t load, or Positron will behave strangely. Here’s how to fix the most common problems.

4.12.1 A Panel Disappeared

You accidentally closed the Console, Terminal, or Variables pane and can’t find it. This happens to everyone. Go to the View menu at the top and look for the panel you need — View → Terminal, View → Console, etc. You can also use the Command Palette: type the name of the panel you’re looking for.

4.12.2 Console Won’t Start

The R or Python console fails to launch, shows errors, or hangs. Check the Output panel (View → Output) and select “R” or “Python” from the dropdown — this shows diagnostic messages that often explain the actual error. Also check the status bar to verify the interpreter path is correct. If all else fails, restart Positron.

4.12.3 Wrong Interpreter Running

Code runs but uses unexpected package versions or the wrong Python/R. Check the status bar at the bottom — it shows which R and Python are active. If it’s wrong, use the Command Palette to reselect (R: Select R Binary or Python: Select Interpreter).

4.12.4 Everything Feels Broken

When Positron is behaving strangely and you’re not sure why, restart it. Close Positron completely and reopen your project. This fixes most transient issues — stuck processes, stale caches, panels that won’t respond.

If problems persist after a restart, check .positron/settings.json in your project folder for stale interpreter paths that might be pointing to environments or R versions that no longer exist.

Claude Code

Claude Code is good at diagnosing Positron issues because it can check your settings, environment paths, and installed packages all at once.

Positron is acting weird — my R console started but it says packages are missing that I already installed. The status bar shows R 4.4.2 and renv is active. What should I check?

Claude will check your renv status, verify the library path, and identify whether packages need to be restored or if there’s a version mismatch.

4.13 Extensions

Positron comes with most of what you need built in. A few extensions are worth adding:

Quarto — for .qmd file support (syntax highlighting, render button, preview). May already be installed.
Jupyter — for Python notebook support, which Quarto uses when rendering Python .qmd files.
Claude Code — the AI coding assistant, if you’re using it.

Install extensions through the Extensions panel (Cmd+Shift+X / Ctrl+Shift+X), search for the name, and click Install.

Start Minimal

Don’t install a dozen extensions on day one. Start with the essentials above and add more only when you encounter a specific need. Too many extensions can slow things down and add complexity.

4.14 Project Settings

Positron stores project-specific settings in a .positron/ folder inside your project. When you select an R version or Python interpreter through the Command Palette, Positron remembers that choice here. The folder is hidden by default (the . prefix hides it in most file browsers), and you normally won’t need to look at it — Positron manages it for you through the Command Palette.

You generally don’t need to think about this. The Command Palette handles most configuration, and Claude Code can adjust settings for you when needed. If something goes wrong with interpreter detection — Positron suddenly uses the wrong R version or Python environment — checking inside .positron/ for stale settings is a reasonable troubleshooting step. You can also safely delete the folder; Positron will recreate it next time you select an interpreter.