Stat DS Computing Wiki - Recent changes [en]

Overleaf

Ajshen — Fri, 30 Oct 2026 21:20:55 GMT

← Older revision		Revision as of 21:20, 30 October 2026
Line 1:		Line 1:
	<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->		<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->
	[[Typesetting]]		[[Category:Typesetting]]

	'''[https://www.overleaf.com Overleaf]''' is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.		'''[https://www.overleaf.com Overleaf]''' is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.

AI Agents: A Primer

Ajshen — Thu, 29 Oct 2026 05:41:27 GMT

← Older revision		Revision as of 05:41, 29 October 2026
(9 intermediate revisions by the same user not shown)
Line 9:		Line 9:
	'''Based on a StatBytes talk'''<br>		'''Based on a StatBytes talk'''<br>
	This article is adapted from the StatBytes talk [https://drive.google.com/drive/folders/1KnyUo9YNr2XL9N5nJgpzW5jWyulSfTIg?usp=drive_link\|''Piloting the Suit: Workflow tips for agentic AI in statistical research'']. A small demo repository that goes with it is at [https://github.com/Alex-Shen-CMU/statbytes-agentic-example github.com/Alex-Shen-CMU/statbytes-agentic-example]. Most examples below use Claude Code, but almost everything applies to other coding agents too.		This article is adapted from the StatBytes talk [https://drive.google.com/drive/folders/1KnyUo9YNr2XL9N5nJgpzW5jWyulSfTIg?usp=drive_link\|''Piloting the Suit: Workflow tips for agentic AI in statistical research'']. A small demo repository that goes with it is at [https://github.com/Alex-Shen-CMU/statbytes-agentic-example github.com/Alex-Shen-CMU/statbytes-agentic-example]. Most examples below use Claude Code, but almost everything applies to other coding agents too.
			<br><br>
			See [https://github.com/Alex-Shen-CMU/stats-agent-setup https://github.com/Alex-Shen-CMU/stats-agent-setup] for a collection of commonly used agent skills and agent instruction files relevant for statistics research.
	</div>		</div>

Line 210:		Line 212:

	A great suit makes a skilled pilot '''superhuman'''. It makes an unskilled pilot crash '''faster'''.		A great suit makes a skilled pilot '''superhuman'''. It makes an unskilled pilot crash '''faster'''.

	~~<!-- SCREENSHOT: Slide "Agentic AI is an Iron Man suit" (final overlay). -->~~
	~~[[File:Agent-iron-man-suit.png\|thumb\|center\|650px\|You are the pilot; the agent is the suit.]]~~

	== Best Practices ==		== Best Practices ==
Line 290:		Line 289:

	A good prompt has five parts: the '''goal''', the relevant '''context''' (and where to find it), the '''constraints''', a checkable '''definition of done''', and an instruction to '''plan and ask questions first'''.		A good prompt has five parts: the '''goal''', the relevant '''context''' (and where to find it), the '''constraints''', a checkable '''definition of done''', and an instruction to '''plan and ask questions first'''.

	~~<!-- SCREENSHOT: Slide "Prompts as specs: before and after" (final overlay). -->~~
	~~[[File:Agent-prompt-before-after.png\|thumb\|center\|700px\|A vague prompt vs. a structured one.]]~~

	== Skills ==		== Skills ==
Line 347:		Line 343:
	Because skills can bundle scripts, they also let the agent ''run'' a deterministic tool instead of ''regenerating'' its logic each time. A summary script that always computes Monte Carlo standard errors the same way is more reliable than asking the model to rewrite that code in every session, and it saves tokens too.		Because skills can bundle scripts, they also let the agent ''run'' a deterministic tool instead of ''regenerating'' its logic each time. A summary script that always computes Monte Carlo standard errors the same way is more reliable than asking the model to rewrite that code in every session, and it saves tokens too.

	<!-- SCREENSHOT: A Claude Code session where the agent picks up a skill automatically (e.g. a request to "run a simulation study comparing ..." with the agent reading .claude/skills/simstudy/SKILL.md). -->
	~~[[File:Claude-code-skill-invocation.png\|thumb\|center\|600px\|The agent loading a skill when a request matches its description.]]~~

	<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">		<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
Line 401:		Line 395:
	* '''Git is your undo button:''' work on branches, protect <code>main</code>, and review every change before it is merged.		* '''Git is your undo button:''' work on branches, protect <code>main</code>, and review every change before it is merged.

	~~<!-- SCREENSHOT: Slide "A concrete workflow: my setup" (laptop → dept. server with tmux + Claude Code + repo clone → GitHub and HPC cluster). -->~~		For a complete end-to-end workflow built on this setup, in which tasks are written as GitHub issues and the agent plans, implements, runs experiments on the cluster, and opens a pull request for review, see [[Agentic Workflow via GitHub Issues]].
	~~[[File:Agent-remote-server-setup.png\|thumb\|center\|700px\|Running the agent on an always-on server, with access to GitHub and the cluster.]]~~

	For a complete end-to-end workflow built on this setup, in which tasks are written as GitHub issues and the agent plans, implements, runs experiments on the cluster, and opens a pull request for review, see [[~~Claude Code~~ GitHub ~~Issue Workflow~~]]. ~~<!-- TODO: fix this link to match the actual title of the GitHub issue workflow article -->~~

	== What Goes in CLAUDE.md ==		== What Goes in CLAUDE.md ==
Line 425:		Line 416:

	Things that belong elsewhere: long procedures (make them [[#Skills\|skills]]), anything secret such as passwords or tokens (never put these in the repository), and task-specific plans (put them in a <code>PLAN.md</code> or an issue).		Things that belong elsewhere: long procedures (make them [[#Skills\|skills]]), anything secret such as passwords or tokens (never put these in the repository), and task-specific plans (put them in a <code>PLAN.md</code> or an issue).

	~~<!-- SCREENSHOT: Slide "A concrete workflow: making it work" (left column, the CLAUDE.md terminal example). -->~~
	~~[[File:Claude-md-example.png\|thumb\|center\|450px\|An example CLAUDE.md.]]~~

	== Common Pitfalls ==		== Common Pitfalls ==
Line 445:		Line 433:

	<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">		<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
	'''Note:''' The tools change quickly, but the principles here don't: keep the context small and focused, write prompts like specifications, plan before building, and stay the pilot. For a full worked example, see [[~~Claude Code~~ GitHub ~~Issue Workflow~~]] and the [https://github.com/Alex-Shen-CMU/statbytes-agentic-example demo repository]. <!-- TODO: fix this link to match the actual title of the GitHub issue workflow article -->		'''Note:''' The tools change quickly, but the principles here don't: keep the context small and focused, write prompts like specifications, plan before building, and stay the pilot. For a full worked example, see [[Agentic Workflow via GitHub Issues]] and the [https://github.com/Alex-Shen-CMU/statbytes-agentic-example demo repository]. <!-- TODO: fix this link to match the actual title of the GitHub issue workflow article -->
	</div>		</div>

File:Agent-dont-be-that-guy.png

Ajshen — Thu, 29 Oct 2026 05:23:36 GMT

Ajshen uploaded File:Agent-dont-be-that-guy.png

New page

File:Agent-misconception.png

Ajshen — Thu, 29 Oct 2026 05:21:31 GMT

Ajshen uploaded File:Agent-misconception.png

New page

File:Agent-time-cost.png

Ajshen — Thu, 29 Oct 2026 05:20:00 GMT

Ajshen uploaded File:Agent-time-cost.png

New page

File:Coding-agent-features.png

Ajshen — Thu, 29 Oct 2026 05:18:46 GMT

Ajshen uploaded File:Coding-agent-features.png

New page

File:Agent-context-window.png

Ajshen — Thu, 29 Oct 2026 05:16:44 GMT

Ajshen uploaded File:Agent-context-window.png

New page

File:Agent-token-cost.png

Ajshen — Thu, 29 Oct 2026 05:14:40 GMT

Ajshen uploaded File:Agent-token-cost.png

New page

File:Coding-agent-read-write-execute.png

Ajshen — Thu, 29 Oct 2026 05:11:52 GMT

Ajshen uploaded File:Coding-agent-read-write-execute.png

New page

AI Agents: A Primer

Ajshen — Thu, 29 Oct 2026 05:09:53 GMT

The landscape

← Older revision		Revision as of 05:09, 29 October 2026
Line 99:		Line 99:

	Terminal-native agents are a natural fit for statistics research, because so much of our work already happens in a shell: <code>Rscript</code>, <code>python</code>, <code>make</code>, <code>git</code>, <code>ssh</code>, and Slurm.		Terminal-native agents are a natural fit for statistics research, because so much of our work already happens in a shell: <code>Rscript</code>, <code>python</code>, <code>make</code>, <code>git</code>, <code>ssh</code>, and Slurm.

	~~<!-- SCREENSHOT: statbytes_figures/claude_code.png from the slides. -->~~
	~~[[File:Claude-code-terminal.png\|thumb\|center\|600px\|Claude Code running in a terminal.]]~~

	=== Core features: read, write, execute ===		=== Core features: read, write, execute ===

File:Agentic-ai-agent-loop.png

Ajshen — Thu, 29 Oct 2026 05:07:43 GMT

Ajshen uploaded File:Agentic-ai-agent-loop.png

New page

File:Agentic-ai-llm-harness.png

Ajshen — Thu, 29 Oct 2026 05:05:10 GMT

Ajshen uploaded File:Agentic-ai-llm-harness.png

New page

AI Agents: A Primer

Ajshen — Thu, 29 Oct 2026 05:02:19 GMT

← Older revision		Revision as of 05:02, 29 October 2026
Line 8:		Line 8:
	<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">		<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
	'''Based on a StatBytes talk'''<br>		'''Based on a StatBytes talk'''<br>
	This article is adapted from the StatBytes talk ''Piloting the Suit: Workflow tips for agentic AI in statistical research''. A small demo repository that goes with it is at [https://github.com/Alex-Shen-CMU/statbytes-agentic-example github.com/Alex-Shen-CMU/statbytes-agentic-example]. Most examples below use Claude Code, but almost everything applies to other coding agents too.		This article is adapted from the StatBytes talk [https://drive.google.com/drive/folders/1KnyUo9YNr2XL9N5nJgpzW5jWyulSfTIg?usp=drive_link\|''Piloting the Suit: Workflow tips for agentic AI in statistical research'']. A small demo repository that goes with it is at [https://github.com/Alex-Shen-CMU/statbytes-agentic-example github.com/Alex-Shen-CMU/statbytes-agentic-example]. Most examples below use Claude Code, but almost everything applies to other coding agents too.
	</div>		</div>

AI Agents: A Primer

Ajshen — Thu, 29 Oct 2026 04:55:34 GMT

Created page with " Category:AI Tools '''Agentic AI''' tools are AI systems that don't just answer questions: they take actions. An agent can search for papers, read your files, write and run code, launch jobs on a cluster, and look at the results, all in a loop, until the task you gave it is done. For statistical research, the most mature agents today are '''AI coding agents''' such as [https:..."

New page

[[Category:AI Tools]]

'''Agentic AI''' tools are AI systems that don't just answer questions: they take actions. An agent can search for papers, read your files, write and run code, launch jobs on a cluster, and look at the results, all in a loop, until the task you gave it is done. For statistical research, the most mature agents today are '''AI coding agents''' such as [https://www.claude.com/product/claude-code Claude Code], OpenAI's Codex CLI, and Google's Gemini CLI. They run in your terminal and work directly on your repository.

These tools can save an enormous amount of time, and they can also waste an enormous amount of time (and money). The difference is almost entirely in how they are used. This article explains how agents work, where their costs come from, and a set of concrete practices for getting good results from them in research.

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Based on a StatBytes talk'''<br>
This article is adapted from the StatBytes talk ''Piloting the Suit: Workflow tips for agentic AI in statistical research''. A small demo repository that goes with it is at [https://github.com/Alex-Shen-CMU/statbytes-agentic-example github.com/Alex-Shen-CMU/statbytes-agentic-example]. Most examples below use Claude Code, but almost everything applies to other coding agents too.
</div>

== What Is an Agentic AI? ==
An agent has two parts: a '''large language model (LLM)''' that does the thinking, and a '''harness''' that gives the model a way to act on the world.

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #d6eaf3; color: #1d5670; padding: 10px; text-align: left;" | The LLM (the brain)
! style="width: 50%; background-color: #d4edda; color: #155724; padding: 10px; text-align: left;" | The harness (the body)
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* '''Text in, text out:''' At its core, the model predicts the next token given everything before it.
* '''Reasons and plans:''' It decides what to do next, including ''which tool to call''.
* '''Stateless:''' It knows only what is currently in its context window. It has no memory of yesterday's session unless something puts that information back in front of it.
| style="padding: 15px;" |
* '''Runs the loop:''' It sends the conversation to the model, receives a tool call, executes it, and sends back the result.
* '''Executes tools:''' Web search, reading PDFs, loading data, running code, editing files.
* '''Manages context and memory:''' It decides what goes into the model's context and loads standing instructions.
* '''Enforces permissions:''' It decides what the agent may do without asking, and sandboxes what it runs.
|}

The model and harness talk through '''tool calls''' and '''observations'''. The model emits something like <code>{search: "Conformal Prediction"}</code>. The harness runs the search and returns "10 results: arXiv, ..." as an observation, which becomes part of the conversation for the next step. Around this exchange sit two more parties: '''you''', who supply the goal, the constraints, and the final judgment, and '''the world''', meaning papers, datasets, your files, compute, and the web.


[[File:Agentic-ai-llm-harness.png|thumb|center|700px|An agent is an LLM plus a harness, connected by tool calls and observations.]]

In one sentence: '''an agent is an LLM in a loop, with tools, running until the task is done.'''

=== The agent loop ===
A single request like "What are the extensions of conformal prediction for dependent data?" becomes many turns of the same loop:

# '''Gather context:''' search for papers, read PDFs, load data.
# '''Take action:''' analyze, compute, draft.
# '''Verify:''' cross-check sources and numbers, run the tests.
# Repeat until the model decides no more tool calls are needed, then hand you a summary and sources to review.

One detail matters a great deal for cost: '''every trip around the loop re-sends the entire conversation to the model.''' This is covered in [[#The Cost of Using Agents|The Cost of Using Agents]] below.


[[File:Agentic-ai-agent-loop.png|thumb|center|650px|The agent loop: gather context, act, verify, repeat.]]

=== What can agents do? ===
Although they are marketed as coding tools, coding agents are general-purpose research assistants that happen to live next to your code.

{| class="wikitable" style="width: 100%;"
|-
! style="background-color: #d6eaf3;" | Software
! style="background-color: #d4edda;" | Computation and data
! style="background-color: #e6dcf0;" | Research writing and reading
|- style="vertical-align: top;"
|
* '''Write code:''' simulations, samplers, neural estimators
* '''Debug:''' read tracebacks, bisect regressions
* '''Refactor:''' turn a script into a package, port R to Python and back
* '''Write tests:''' unit tests, coverage checks, CI
|
* '''Run experiments:''' launch, monitor, collect results
* '''Analyze data:''' EDA, summaries, diagnostic plots
* '''Make figures:''' iterate on a plot, including from a screenshot of a figure you like
* '''Reproduce:''' re-run a paper's code from its repository
|
* '''Literature:''' search, summarize, compare methods
* '''Write LaTeX:''' fix compile errors, build tables from CSVs
* '''Review:''' check a derivation, revise a paper draft
* '''Admin:''' issues, emails, documentation, READMEs
|}

== AI Coding Agents ==

=== The landscape ===
Coding agents fall roughly into two groups. They share the same core loop, and differ in harness, model, and pricing. '''The landscape changes monthly''', so treat any list like this as a snapshot.

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #f5d5db; color: #7a0b1e; padding: 10px; text-align: left;" | Terminal-native
! style="width: 50%; background-color: #d6eaf3; color: #1d5670; padding: 10px; text-align: left;" | IDE and cloud
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* '''Claude Code''' (Anthropic)
* '''Codex CLI''' (OpenAI)
* '''Gemini CLI''' (Google)
* '''Aider''', '''OpenCode''' (open source)
| style="padding: 15px;" |
* '''Cursor''': an AI-first editor
* '''GitHub Copilot''': agent mode inside VS Code and other editors
* '''Cline''' and similar editor extensions
* '''Cloud agents''' (Devin, Jules, Copilot coding agent): work on a remote copy of your repository and hand back a pull request
|}

Terminal-native agents are a natural fit for statistics research, because so much of our work already happens in a shell: <code>Rscript</code>, <code>python</code>, <code>make</code>, <code>git</code>, <code>ssh</code>, and Slurm.


[[File:Claude-code-terminal.png|thumb|center|600px|Claude Code running in a terminal.]]

=== Core features: read, write, execute ===
Every coding agent is built on three capabilities:

* '''Read''' (<code>cat</code>, <code>grep</code>, <code>glob</code>): navigate the repository and find the 3 relevant files out of your 300.
* '''Write''' (edit, create): make targeted diffs rather than rewriting whole files. You can require approval for each edit.
* '''Execute''' (<code>bash</code>): run <code>Rscript</code>, <code>pytest</code>, <code>make</code>, <code>git</code>, and so on, then '''read the output'''.

The output of each command becomes new context, and the agent iterates until the tests pass. This is the key leap over chat assistants: '''the agent runs the code and sees what happens.''' There is no more copy-paste ping-pong between a browser tab and your terminal.


[[File:Coding-agent-read-write-execute.png|thumb|center|650px|Read, write, execute, and feed the output back in.]]

=== Features beyond the basics ===
Modern harnesses add a lot on top of the core loop:

* '''Web search:''' look up documentation, papers, and error messages.
* '''MCP servers:''' the [https://modelcontextprotocol.io Model Context Protocol] connects the agent to outside services such as GitHub, Slack, Notion, or Zotero.
* '''Test writing:''' unit tests, edge cases, and regression tests.
* '''SSH and Slurm:''' with SSH access configured, the agent can run <code>sbatch</code> and <code>squeue</code> on a cluster and pull results back.
* '''Subagents:''' parallel workers that each start with a fresh context and report back only a summary.
* '''Multimodal input:''' screenshots, plots, and PDFs of papers. The agent can also render a plot and ''look at its own output'' to fix overlapping labels before you ever see it.
* '''Memory files:''' <code>CLAUDE.md</code> (or <code>AGENTS.md</code> for some other agents) holds your project conventions and is loaded into every session.
* '''Skills and hooks:''' reusable workflows and automatic actions (see [[#Skills|Skills]] below).


[[File:Coding-agent-features.png|thumb|center|650px|Features modern coding agents provide on top of the core loop.]]

== The Cost of Using Agents ==
Agents have two costs: '''tokens''' (money and usage limits) and '''your time'''. They are linked, since a confused agent burns both, but they are not the same thing. A cheap, fast agent can still waste your afternoon.

=== Tokens ===
Recall that every turn of the loop re-sends the whole conversation. If the context grows by a roughly constant amount each turn, then '''the context size grows linearly and the total number of tokens processed grows quadratically''' in the number of turns. Prompt caching lowers the price of re-reading earlier context, but it does nothing about the context window's hard limit.


[[File:Agent-token-cost.png|thumb|center|700px|Context grows linearly, total tokens grow quadratically.]]

The biggest token sinks are:

* '''Long contexts:''' every turn re-reads the whole history.
* '''Dumping big outputs:''' a 50,000-line log, a full CSV, or <code>print(model)</code> on a large object, all of which stay in context for every later turn.
* '''High reasoning effort:''' thinking tokens are billed too.
* '''Open-ended prompts:''' the agent explores the whole repository to guess what you meant.
* '''Lost threads:''' re-explaining everything after the context is compacted, polluted, or gone because you started a new session.

=== Context rot ===
The context window is the agent's entire working memory. In a long session it fills up with a system prompt, memory files, and your task, plus a lot of noise: files it read that turned out to be irrelevant, logs and tracebacks, failed attempts, and old tangents. The useful work is often a small slice at the end.

That noise costs tokens on every turn, and it '''also degrades quality'''. Models get measurably worse as their context fills with irrelevant material (often called "context rot"). They lose instructions given early in the session, repeat fixes that already failed, and contradict earlier decisions. Eventually the agent hits the context limit and has to compact (summarize) its history, which loses detail.


[[File:Agent-context-window.png|thumb|center|700px|A full context window is mostly noise.]]

=== Your time ===
Where does the wall-clock time of a "2-hour" agent session actually go? In an inefficient session, most of it goes to clarifying, waiting, back-and-forth, and fixing things. In an efficient one, you spend a few minutes on a spec and a plan, the agent does the work in the background, and you spend a few minutes reviewing the diff.


[[File:Agent-time-cost.png|thumb|center|700px|Where the time goes in an inefficient vs. an efficient session.]]

The main time sinks are:

* '''Wrong direction:''' the agent confidently builds the wrong thing, and you notice 30 minutes later.
* '''Opaque code:''' you end up debugging 600 lines you didn't write and don't understand.
* '''Memory loss:''' sessions don't share context, so threads get lost and rebuilt repeatedly.
* '''Ambiguity ping-pong:''' a vague ask produces a vague result, so you ask again.

== The Role of the Researcher ==

=== A common misconception ===
Because agents ''talk'' like humans, it is tempting to assume they ''think'' like humans, and to treat them as a colleague who shares your intuitions and background. This leads to underspecified requests and surprising results.

A more useful mental model: '''we have found a way to write computer programs in natural language.''' Your prompt is source code. Like any program, it does what you ''wrote'', not what you ''meant''. Each step from assembly to C to Python/R to English has made programming higher-level and easier to write, but every step is still programming.


[[File:Agent-misconception.png|thumb|center|650px|Prompts are programs written in English.]]

=== You still need to understand code ===
Using AI for statistics research still requires knowing statistics, or you can't tell a valid result from a confident hallucination. In the same way, using AI for code still requires knowing how code works, or you can't tell a good design from 3,000 lines of spaghetti.

You don't need to write every line yourself, but you do need to know enough to:
* specify the architecture you want,
* read a diff,
* spot a silent bug, and
* say "no, do it this way."


[[File:Agent-dont-be-that-guy.png|thumb|center|450px|What happens when nobody reviews the agent's work.]]

=== Agentic AI is an Iron Man suit ===
A good way to think about the division of labor is an Iron Man suit:

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #f5d5db; color: #7a0b1e; padding: 10px; text-align: left;" | The pilot (you)
! style="width: 50%; background-color: #d6eaf3; color: #1d5670; padding: 10px; text-align: left;" | The suit (the agent)
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* Where to go
* What "done" means
* What is ''correct''
* When to abort
* Taste and judgment
| style="padding: 15px;" |
* Speed
* Stamina (it works 24/7)
* Breadth of knowledge
* Boilerplate at scale
* Tireless retries
|}

A great suit makes a skilled pilot '''superhuman'''. It makes an unskilled pilot crash '''faster'''.


[[File:Agent-iron-man-suit.png|thumb|center|650px|You are the pilot; the agent is the suit.]]

== Best Practices ==

=== Saving tokens ===
{| class="wikitable" style="width: 100%;"
|-
! style="width: 22%; background-color: #f8d7da; color: #721c24;" | Problem
! style="background-color: #d4edda; color: #155724;" | Fix
|-
| '''Long contexts'''
| '''One task per session.''' Use <code>/clear</code> between tasks, and <code>/compact</code> with a note on what to keep when you need to continue. A fresh context is cheaper ''and'' smarter.
|-
| '''Big outputs'''
| '''Keep irrelevant data out of the context.''' Use <code>grep</code> or <code>tail</code> on logs, summarize data with <code>head()</code> or <code>str()</code>, and write results to files instead of printing them. Delegate noisy searches to a '''subagent''' that returns only a summary.
|-
| '''Reasoning effort'''
| '''Match effort to the task:''' low for renames and typos, high for design decisions and nasty bugs. Use a smaller, faster model for grunt work.
|-
| '''Needless exploring'''
| '''Say where to look.''' Point at files (<code>@R/sampler.R</code>) and name functions. Don't make the agent search for things you already know.
|-
| '''Going off track'''
| '''Interrupt early''' with <code>Esc</code>. <code>Esc Esc</code> or <code>/rewind</code> rolls back to a checkpoint. Restarting from a good state beats a long correction thread.
|-
| '''Lost threads'''
| '''Persist state outside the chat:''' <code>CLAUDE.md</code> for conventions, a <code>PLAN.md</code> checklist for multi-session work, and GitHub issues or markdown files for the backlog.
|}

=== Saving time ===
{| class="wikitable" style="width: 100%;"
|-
! style="width: 22%; background-color: #f8d7da; color: #721c24;" | Problem
! style="background-color: #d4edda; color: #155724;" | Fix
|-
| '''Unclear goal'''
| '''Say what done looks like:''' the goal, the constraints, and a concrete check ("done when the tests pass and the estimates match <code>lm()</code>"). '''Tell it to ask follow-up questions''' before starting.
|-
| '''Wrong direction'''
| '''Plan first.''' Use plan mode, or say "propose a plan, don't edit yet." Reviewing a 10-line plan beats reviewing a 600-line diff.
|-
| '''Opaque code'''
| '''Take small steps''' and commit each one. Ask for '''tests first''', then the implementation. Ask the agent to explain any change you don't follow.
|-
| '''Repeating yourself'''
| '''Package recurring workflows''' as skills or custom slash commands (e.g. <code>/simstudy</code>; see [[#Skills|Skills]]). Use hooks to run formatters or linters automatically after edits.
|-
| '''Babysitting'''
| '''Use auto mode.''' Allow-list safe commands (<code>pytest</code>, <code>git diff</code>, <code>Rscript</code>). Run in a sandbox or container if you want to give the agent more autonomy.
|-
| '''Waiting'''
| '''Run it in the background''' (e.g. in <code>tmux</code>) and do other work. Run parallel sessions on separate <code>git worktree</code>s for independent tasks.
|}

=== Prompts as specs ===
Since prompts are programs, write them like specifications. Compare:

<div style="background-color: #f8f9fa; border-left: 4px solid #C0392B; padding: 15px; margin-bottom: 10px;">
'''Vague:'''
<pre>
> make the simulation faster
</pre>
The agent reads 40 files, rewrites the random number generator, parallelizes the wrong loop, and breaks reproducibility. An hour later your session usage is gone and the result is unusable.
</div>

<div style="background-color: #f8f9fa; border-left: 4px solid #2E8B57; padding: 15px; margin-bottom: 10px;">
'''Structured:'''
<pre>
> Goal: speed up simulate_paths() in @src/sim.py; it is 90% of runtime.
Context: profile output in prof.txt. The inner loop over t is pure Python.
Constraints: keep the seeded RNG stream identical; no new dependencies
beyond numba.
Done when: tests/test_sim.py passes and bench.py shows >=5x speedup.
First: propose a plan and ask me any questions before editing.
</pre>
</div>

A good prompt has five parts: the '''goal''', the relevant '''context''' (and where to find it), the '''constraints''', a checkable '''definition of done''', and an instruction to '''plan and ask questions first'''.


[[File:Agent-prompt-before-after.png|thumb|center|700px|A vague prompt vs. a structured one.]]

== Skills ==

=== The problem skills solve ===
After a few weeks with an agent, you will notice that you keep typing the same instructions. Every simulation study needs the same seeding conventions, the same output format, and the same summary table. Every figure should use the same theme and fonts. Every Slurm script needs the same partition and module setup. You have two obvious options, and both are bad:

* '''Retype the instructions every time.''' This is tedious, and you will forget something, so results drift from one session to the next.
* '''Put everything in <code>CLAUDE.md</code>.''' The memory file is loaded into ''every'' session, so a long list of procedures costs tokens on every turn of every task, including the ones that have nothing to do with simulation studies. It also adds to the noise that causes context rot.

'''Skills''' are the middle ground: packaged, reusable instructions that are '''available in every session but loaded only when needed'''.

=== How skills work ===
A skill is a folder containing a <code>SKILL.md</code> file, optionally with supporting files such as templates, reference documents, or scripts. In Claude Code, project skills live in <code>.claude/skills/<skill-name>/</code> inside the repository (so they are shared with everyone who clones it), and personal skills live in <code>~/.claude/skills/</code>.

The <code>SKILL.md</code> file starts with a short header giving the skill's name and a description of when to use it:

<pre>
.claude/skills/simstudy/
├── SKILL.md
├── templates/
│ ├── run_sim.R
│ └── simstudy.slurm
└── scripts/
└── summarize_results.R
</pre>

<pre>
---
name: simstudy
description: Set up, run, and summarize a Monte Carlo simulation study.
Use when the user asks to design or run a simulation study, compare
estimators by simulation, or summarize simulation results.
---

# Simulation studies

1. Before writing code, confirm with the user: the data-generating
process, the estimators being compared, the parameter grid, and the
number of replications.
2. Copy templates/run_sim.R. Each replication takes (scenario, rep_id)
and seeds with set.seed(1e5 * scenario + rep_id).
3. Write one .rds file per scenario to results/raw/. Never print raw
results to the console.
4. Run a 10-replication smoke test locally before submitting anything.
5. Submit with templates/simstudy.slurm as an array job, one task
per scenario.
6. Summarize with scripts/summarize_results.R: bias, RMSE, coverage,
and Monte Carlo standard errors for each.
</pre>

The key mechanism is '''progressive disclosure'''. At the start of a session, the agent sees only the name and description of each skill, which costs a few dozen tokens apiece. When a request matches a description, the agent reads the full <code>SKILL.md</code>, and it opens the templates or runs the scripts only when it reaches the step that needs them. You can have dozens of skills installed at almost no standing cost. You can also invoke a skill directly by name, for example by typing <code>/simstudy</code>.

Because skills can bundle scripts, they also let the agent ''run'' a deterministic tool instead of ''regenerating'' its logic each time. A summary script that always computes Monte Carlo standard errors the same way is more reliable than asking the model to rewrite that code in every session, and it saves tokens too.


[[File:Claude-code-skill-invocation.png|thumb|center|600px|The agent loading a skill when a request matches its description.]]

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Skills, CLAUDE.md, and hooks:''' Use <code>CLAUDE.md</code> for short facts that are true in every session ("this project uses renv", "never run heavy jobs on the login node"). Use a '''skill''' for a procedure that is needed only for certain tasks. Use a '''hook''' for something that must ''always'' happen after a given action, such as running <code>styler</code> after every edit to an R file. Hooks are enforced by the harness, while skills and memory files are instructions the model may or may not follow perfectly.
</div>

=== Example skills for statistics research ===
{| class="wikitable" style="width: 100%;"
|-
! style="width: 20%;" | Skill
! What it packages
|-
| '''Simulation study'''
| The data-generating process / estimator / replication layout, seeding conventions, file outputs, Slurm array template, and a standard summary of bias, RMSE, coverage, and Monte Carlo error.
|-
| '''Paper figures'''
| Your plotting theme, font sizes matched to the paper's column width, colorblind-safe palette, and export settings (vector PDF, correct dimensions). Can include a script that checks for overlapping labels.
|-
| '''LaTeX tables'''
| Turning a CSV of results into a <code>booktabs</code> table with consistent rounding, bolded best entries, and standard errors in parentheses.
|-
| '''Cluster jobs'''
| The department cluster's partitions, module loads, resource defaults, and etiquette rules, plus how to check on and resubmit failed array tasks.
|-
| '''R package check'''
| Running <code>devtools::document()</code>, <code>devtools::test()</code>, and <code>R CMD check</code>, and fixing NOTEs and WARNINGs in a fixed order.
|-
| '''Reproducibility audit'''
| A checklist for a project before submission or code release: pinned environments (<code>renv</code> / <code>uv</code>), seeds, hard-coded paths, and whether a clean clone reproduces every figure.
|-
| '''Paper reading notes'''
| A fixed template for summarizing a paper: setting, assumptions, main result, proof technique, and how it relates to your work. Useful for building a consistent literature file.
|-
| '''Referee report'''
| Your structure for reviewing a manuscript, from summary through major and minor comments, with a reminder to check derivations and simulation designs.
|}

=== Tips for writing skills ===
* '''The description is what triggers the skill.''' Write it as "what this does, and when to use it", using the words you would actually type in a request. A skill with a vague description will never be picked up.
* '''Keep <code>SKILL.md</code> short.''' Put long reference material in separate files and tell the agent when to open them.
* '''Write the skill after doing the task by hand once.''' Do the workflow with the agent interactively, then ask it to turn the session into a skill and edit the result.
* '''Commit project skills to the repository''' so collaborators (and their agents) follow the same conventions.
* '''Only install skills from sources you trust.''' A skill can contain scripts that the agent will run, so read third-party skills before installing them.
* '''Check your agent's documentation.''' The skill format has been adopted by several coding agents besides Claude Code, but locations and details vary between tools and change over time.

== Running Agents on a Remote Server ==
Agents are most useful when they can run unattended, so it pays to run them somewhere that stays on. A simple setup is to run the agent inside a <code>tmux</code> session on an always-on department server, with your laptop (or phone) serving only as a window into it:

* '''tmux:''' start a session with <code>tmux new -s claude</code>, detach with <code>Ctrl-b d</code>, and reattach from anywhere with <code>tmux attach -t claude</code>. The agent keeps working when you close your laptop.
* '''SSH:''' set up passwordless key-based authentication and put host details in <code>~/.ssh/config</code>, so the agent can reach the cluster without ever seeing a password prompt.
* '''Shared server etiquette:''' the agent edits code and submits jobs; the cluster does the computing. Never let an agent run heavy computations on a shared login or interactive server.
* '''Git is your undo button:''' work on branches, protect <code>main</code>, and review every change before it is merged.


[[File:Agent-remote-server-setup.png|thumb|center|700px|Running the agent on an always-on server, with access to GitHub and the cluster.]]

For a complete end-to-end workflow built on this setup, in which tasks are written as GitHub issues and the agent plans, implements, runs experiments on the cluster, and opens a pull request for review, see [[Claude Code GitHub Issue Workflow]]. 

== What Goes in CLAUDE.md ==
<code>CLAUDE.md</code> sits at the root of the repository and is read at the start of every session. Keep it short, specific, and limited to things that are true for every task. An example:

<pre>
# Project: statbytes-agentic-example

## Cluster
- ssh: user@cluster (keys already set up)
- The cluster runs Slurm. Relevant partitions: ...
- Never run heavy jobs on the department server.
- Do not commit Slurm scripts.

## Conventions
- One branch per task.
- Never force-push; never touch main.
- Don't guess; ask clarifying questions.
</pre>

Things that belong elsewhere: long procedures (make them [[#Skills|skills]]), anything secret such as passwords or tokens (never put these in the repository), and task-specific plans (put them in a <code>PLAN.md</code> or an issue).


[[File:Claude-md-example.png|thumb|center|450px|An example CLAUDE.md.]]

== Common Pitfalls ==
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Things to Watch Out For
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px;" |
* '''Merging code you haven't read:''' The agent's code is your code once it is in your paper. Review every diff, and ask for explanations of anything you don't follow.
* '''One endless session:''' Long sessions get more expensive per turn ''and'' worse in quality. Start fresh for each task.
* '''Printing everything:''' Large outputs stay in context for the rest of the session. Write to files and summarize.
* '''Vague requests:''' "Make it better" gets you something different, not necessarily better. Give a goal, constraints, and a definition of done.
* '''Letting it run unchecked on shared resources:''' Allow-list commands deliberately, and keep heavy computation on the cluster's compute nodes.
* '''Giving it more access than it needs:''' Scope tokens (e.g. GitHub) to a single repository, keep secrets out of the repository, and protect your <code>main</code> branch.
* '''Bloated memory files:''' Every line of <code>CLAUDE.md</code> is paid for on every turn. Move procedures into skills.
|}

<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
'''Note:''' The tools change quickly, but the principles here don't: keep the context small and focused, write prompts like specifications, plan before building, and stay the pilot. For a full worked example, see [[Claude Code GitHub Issue Workflow]] and the [https://github.com/Alex-Shen-CMU/statbytes-agentic-example demo repository]. 
</div>

Docker Sandboxes for AI Agents

Ajshen — Mon, 26 Oct 2026 20:53:26 GMT

Created page with " Category:AI Tools Category:Containers and Virtual Environments '''[https://docs.docker.com/ai/sandboxes/ Docker Sandboxes]''' (the <code>sbx</code> command-line tool) runs AI coding agents such as Claude Code, Codex, Copilot, and Gemini inside disposable, isolated micro virtual machines ('''microVMs'''). Inside the sandbox the agent has a full Linux machine to do whateve..."

New page

[[Category:AI Tools]]
[[Category:Containers and Virtual Environments]]

'''[https://docs.docker.com/ai/sandboxes/ Docker Sandboxes]''' (the <code>sbx</code> command-line tool) runs AI coding agents such as Claude Code, Codex, Copilot, and Gemini inside disposable, isolated micro virtual machines ('''microVMs'''). Inside the sandbox the agent has a full Linux machine to do whatever it wants with. Your own computer only exposes the project folder you hand it and the network destinations you allow.

The point is to give an agent real autonomy without handing it your whole computer. It can install packages, run builds, and run tests without asking permission at every step, and it still can't reach your home directory, SSH keys, or cloud credentials.

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Before you start'''<br>
This article covers what Docker Sandboxes are and how to install them. For day-to-day use, see Docker's [https://docs.docker.com/ai/sandboxes/get-started/ getting started guide] and [https://docs.docker.com/ai/sandboxes/usage/ usage guide]. <code>sbx</code> is new and changes quickly between releases, so if a command here doesn't match what you see, trust the [https://docs.docker.com/ai/sandboxes/install/ official install page] and the [https://docs.docker.com/ai/sandboxes/release-notes/ release notes].
</div>

== Overview: Docker Sandboxes for AI Agents ==

=== How it works ===
When you run <code>sbx run claude</code> from a project folder, <code>sbx</code> does the following:

* '''Boots a microVM''' with its own Linux kernel. It uses the operating system's built-in hypervisor: Hypervisor.framework on macOS, Windows Hypervisor Platform on Windows, and KVM on Linux.
* '''Mounts your current folder''' into the VM as the workspace. This folder is the only part of your machine the agent can see.
* '''Starts a private Docker daemon''' inside the VM, so the agent can build images and run containers without touching yours.
* '''Filters outbound network traffic''' through a policy you choose. The presets are ''Open'', ''Balanced'' (deny by default, with common development sites allowed), and ''Locked Down''.
* '''Handles credentials from the host'''. For example, Claude Code's login token stays on your machine rather than being stored in the sandbox. See [https://docs.docker.com/ai/sandboxes/configuration/credentials/ Credentials].

Sandboxes persist after the agent exits. You can stop and resume them, and you delete them when you're done. Everything the agent installed inside the sandbox is discarded at that point, and your project files are left alone. For the details, see [https://docs.docker.com/ai/sandboxes/architecture/ Architecture] and [https://docs.docker.com/ai/sandboxes/security/isolation/ Isolation layers].

=== How it compares ===
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 16%; background-color: #e9ecef; padding: 10px; text-align: left;" |
! style="width: 28%; background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Agent run directly on your machine
! style="width: 28%; background-color: #fff3cd; color: #856404; padding: 10px; text-align: left;" | Agent in a regular Docker container
! style="width: 28%; background-color: #d4edda; color: #155724; padding: 10px; text-align: left;" | Agent in a Docker Sandbox
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 10px;" | '''Isolation boundary'''
| style="padding: 10px;" | None. The agent runs as ''you''.
| style="padding: 10px;" | Linux namespaces. All containers share one kernel, so escaping the container means reaching the host (or Docker Desktop's VM).
| style="padding: 10px;" | A separate VM with its own kernel for each sandbox.
|- style="vertical-align: top; background-color: #ffffff;"
| style="padding: 10px;" | '''Files it can touch'''
| style="padding: 10px;" | Everything your account can read or write, including other repos, <code>~/.ssh</code>, <code>~/.aws</code>, and browser profiles.
| style="padding: 10px;" | Whatever you bind-mount. It's easy to mount too much.
| style="padding: 10px;" | Only the workspace folder.
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 10px;" | '''Network'''
| style="padding: 10px;" | Unrestricted.
| style="padding: 10px;" | Unrestricted by default. Egress filtering is your problem.
| style="padding: 10px;" | Policy-controlled, with presets and per-host allow and deny rules.
|- style="vertical-align: top; background-color: #ffffff;"
| style="padding: 10px;" | '''Running Docker itself'''
| style="padding: 10px;" | Uses your Docker daemon.
| style="padding: 10px;" | Requires mounting the host's Docker socket, which is effectively root on the host.
| style="padding: 10px;" | Uses its own daemon inside the VM. Nothing is shared with the host.
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 10px;" | '''Setup'''
| style="padding: 10px;" | None.
| style="padding: 10px;" | You write and maintain the Dockerfile, mounts, and agent install.
| style="padding: 10px;" | One command. The common agents come preinstalled.
|}

'''Compared with running an agent directly on your machine:''' coding agents protect you mostly by asking permission before running commands. After the fiftieth prompt, most people either click "approve" without reading or turn the prompts off entirely. Inside a sandbox, turning prompts off is much less dangerous. A bad command, a hallucinated <code>rm -rf</code>, or a prompt injection hidden in a README or web page can only reach the workspace and the network hosts you allowed.

'''Compared with plain Docker:''' you ''can'' build your own agent container. To make it safe, though, you have to solve the problems Sandboxes already handle. You need a kernel boundary rather than a shared kernel, outbound filtering, a way to keep API keys out of the container, and a way for the agent to use Docker without mounting the host socket. Sandboxes also don't require Docker Desktop. You may see a <code>docker sandbox</code> command that ships with Docker Desktop. This article uses the standalone <code>sbx</code> CLI instead.

<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Warning: What a sandbox does ''not'' protect'''<br>
* '''Your workspace.''' By default the project folder is mounted read-write, so the agent can still delete or break files in it. Commit before you start, or use [https://docs.docker.com/ai/sandboxes/usage/ clone mode] to give the agent a private copy.
* '''What the agent sends to the model.''' The sandbox limits what the agent can ''touch''. It does not limit what gets sent to the model provider's API as context. Don't put data you aren't permitted to share with a third party (for example, restricted or IRB-protected data) in the workspace.
* '''Hosts you allow.''' The Open policy, or broad allow rules, can still be used to move data out of the sandbox. Tokens you give the agent, such as a GitHub token, can be used for anything they're scoped for.
</div>

See [https://docs.docker.com/ai/sandboxes/security/defaults/ Security defaults] for exactly what is and isn't allowed out of the box.

== Installing on Windows ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Requirements:''' Windows 11 on a 64-bit Intel or AMD processor (Windows on Arm is not supported), hardware virtualization turned on, and administrator rights '''once''' to enable Windows Hypervisor Platform. Run all commands in PowerShell. Steps marked '''(Administrator)''' need an elevated prompt: right-click PowerShell and choose ''Run as administrator''.
</div>

=== Step 1: Check your system ===
<syntaxhighlight lang="powershell">
# Should print "Microsoft Windows 11 ..."
(Get-CimInstance Win32_OperatingSystem).Caption

# Should print AMD64
$env:PROCESSOR_ARCHITECTURE
</syntaxhighlight>

Next, open '''Task Manager → Performance → CPU''' and check that it shows '''Virtualization: Enabled'''. If it shows Disabled, turn on Intel VT-x or AMD-V (SVM) in your BIOS/UEFI settings. Microsoft's guide covers this: [https://support.microsoft.com/en-us/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1 Enable virtualization on Windows].

=== Step 2: Enable Windows Hypervisor Platform (Administrator) ===
<syntaxhighlight lang="powershell">
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All
Restart-Computer
</syntaxhighlight>

After rebooting, check that the feature is on. It should report <code>Enabled</code>:
<syntaxhighlight lang="powershell">
(Get-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform).State
</syntaxhighlight>

If you're on a department-managed laptop without admin rights, this is the one step you'll need IT for.

=== Step 3: Install sbx ===
In a '''regular''' (non-admin) PowerShell window:
<syntaxhighlight lang="powershell">
winget install -h Docker.sbx
</syntaxhighlight>

This installs <code>sbx</code> for your user only, in <code>%LOCALAPPDATA%\DockerSandboxes</code>, and adds it to your user <code>PATH</code>. '''Close and reopen PowerShell''', then confirm that it works:
<syntaxhighlight lang="powershell">
sbx version
</syntaxhighlight>

If you get <code>sbx is not recognized</code>, the <code>PATH</code> change hasn't been picked up yet. Open a new window, or sign out and back in. You can confirm the binary exists with <code>Test-Path "$env:LOCALAPPDATA\DockerSandboxes\bin\sbx.exe"</code>.

To install for every user on a shared machine, use the machine-wide MSI described on the [https://docs.docker.com/ai/sandboxes/install/ install page].

=== Step 4: Sign in ===
<syntaxhighlight lang="powershell">
sbx login
</syntaxhighlight>

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at [https://hub.docker.com/signup Docker Hub]. The [https://docs.docker.com/ai/sandboxes/faq/ FAQ] explains why sign-in is required.

=== Step 5: Run your first sandbox ===
<syntaxhighlight lang="powershell">
cd $HOME\path\to\your-project
git status # commit or stash anything you care about first
sbx run claude
</syntaxhighlight>

The first time you run a sandbox, <code>sbx</code> asks you to choose a default network policy. '''Balanced''' is a sensible starting point. The first run also takes a minute while the agent image downloads. For Claude Code with a Claude subscription, type <code>/login</code> inside the sandbox. For other agents or API keys, see the [https://docs.docker.com/ai/sandboxes/agents/ agent pages].

'''Updating later:''' <code>winget upgrade Docker.sbx</code>

== Installing on macOS ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Requirements:''' a Mac with Apple silicon (M1 or later) running macOS 14 Sonoma or later. Intel Macs are not supported. You also need [https://brew.sh Homebrew]. Run all commands in Terminal.
</div>

=== Step 1: Check your system ===
<syntaxhighlight lang="bash">
uname -m # should print arm64
sw_vers -productVersion # should be 14.0 or higher
brew --version # if this fails, install Homebrew from https://brew.sh
</syntaxhighlight>

=== Step 2: Install sbx ===
<syntaxhighlight lang="bash">
brew trust docker/tap
brew install docker/tap/sbx
</syntaxhighlight>

The first command marks Docker's Homebrew tap as trusted. If Homebrew reports <code>brew trust</code> as an unknown command, run <code>brew update</code> and try again.

Confirm the install:
<syntaxhighlight lang="bash">
sbx version
</syntaxhighlight>

=== Step 3: Sign in ===
<syntaxhighlight lang="bash">
sbx login
</syntaxhighlight>

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at [https://hub.docker.com/signup Docker Hub]. The [https://docs.docker.com/ai/sandboxes/faq/ FAQ] explains why sign-in is required.

=== Step 4: Run your first sandbox ===
<syntaxhighlight lang="bash">
cd ~/path/to/your-project
git status # commit or stash anything you care about first
sbx run claude
</syntaxhighlight>

The first time you run a sandbox, <code>sbx</code> asks you to choose a default network policy. '''Balanced''' is a sensible starting point. For Claude Code with a Claude subscription, type <code>/login</code> inside the sandbox. For other agents or API keys, see the [https://docs.docker.com/ai/sandboxes/agents/ agent pages].

'''Updating later:''' <code>brew upgrade docker/tap/sbx</code>

== Installing on Linux ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Requirements:''' Ubuntu 24.04 or later on x86-64 or 64-bit Arm, KVM hardware virtualization, and <code>sudo</code>. Docker does '''not''' support Ubuntu derivatives such as Linux Mint or Pop!_OS, because the install script can configure the wrong package repository on them. For other distributions, see the [https://github.com/docker/sbx-releases#manual-install-from-release-artifacts release artifacts], which Docker does not test. If you're installing inside a virtual machine, the VM must support nested virtualization.
</div>

<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Shared servers and clusters'''<br>
Installing <code>sbx</code> needs <code>sudo</code> and membership in the <code>kvm</code> group, which you usually won't have on department compute servers or clusters. Run sandboxes on your own machine, or ask the system administrators.
</div>

=== Step 1: Check your system ===
<syntaxhighlight lang="bash">
lsb_release -ds # should be Ubuntu 24.04 or later
uname -m # x86_64 or aarch64
lsmod | grep kvm # should list kvm_intel, kvm_amd, kvm_arm64, or kvm
</syntaxhighlight>

If the last command prints nothing, find out why with:
<syntaxhighlight lang="bash">
sudo apt install cpu-checker
kvm-ok
</syntaxhighlight>

The usual cause is that virtualization is turned off in the BIOS/UEFI.

=== Step 2: Add yourself to the kvm group ===
<syntaxhighlight lang="bash">
sudo usermod -aG kvm $USER
newgrp kvm # or log out and back in
groups | grep -w kvm # should now print your groups, including kvm
</syntaxhighlight>

=== Step 3: Install sbx ===
Choose '''one''' of the following options.

'''Option A: <code>sbx</code> only.''' Choose this if you don't need Docker Engine on the host.
<syntaxhighlight lang="bash">
curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh # adds Docker's apt repository
sudo apt install docker-sbx
</syntaxhighlight>

'''Option B: Docker Engine and <code>sbx</code> together.'''
<syntaxhighlight lang="bash">
curl -fsSL https://get.docker.com | sudo SBX=1 sh
</syntaxhighlight>

If you'd rather read the install script before running it with root privileges, download it first:
<syntaxhighlight lang="bash">
curl -fsSL https://get.docker.com -o get-docker.sh
less get-docker.sh
sudo REPO_ONLY=1 sh get-docker.sh # or SBX=1 for Option B
</syntaxhighlight>

Confirm the install:
<syntaxhighlight lang="bash">
sbx version
</syntaxhighlight>

=== Step 4: Sign in ===
<syntaxhighlight lang="bash">
sbx login
</syntaxhighlight>

This opens a browser so you can sign in with a Docker account. If you don't have one, create one at [https://hub.docker.com/signup Docker Hub]. On a machine without a desktop, see [https://docs.docker.com/ai/sandboxes/troubleshooting/ Troubleshooting].

=== Step 5: Run your first sandbox ===
<syntaxhighlight lang="bash">
cd ~/path/to/your-project
git status # commit or stash anything you care about first
sbx run claude
</syntaxhighlight>

The first time you run a sandbox, <code>sbx</code> asks you to choose a default network policy. '''Balanced''' is a sensible starting point. For Claude Code with a Claude subscription, type <code>/login</code> inside the sandbox. For other agents or API keys, see the [https://docs.docker.com/ai/sandboxes/agents/ agent pages].

'''Updating later:''' <code>sudo apt update && sudo apt install --only-upgrade docker-sbx</code>

<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
'''Next steps:''' Once your first sandbox runs, read the [https://docs.docker.com/ai/sandboxes/usage/ usage guide] for reconnecting, ports, and clone mode. The [https://docs.docker.com/ai/sandboxes/workflows/git/ Git workflows] page covers letting agents push branches, [https://docs.docker.com/ai/sandboxes/governance/access-controls/local/ Local policy] covers tuning network rules, and the [https://docs.docker.com/reference/cli/sbx/ CLI reference] lists every command.
</div>

Overleaf

Ajshen — Mon, 26 Oct 2026 20:48:56 GMT

← Older revision		Revision as of 20:48, 26 October 2026
Line 1:		Line 1:
	<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->		<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->
	[[~~index.php?title=Category:~~Typesetting]]		[[Typesetting]]

	'''[https://www.overleaf.com Overleaf]''' is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.		'''[https://www.overleaf.com Overleaf]''' is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.

Wright GPU Cluster

Areinhar — Fri, 23 Oct 2026 14:22:16 GMT

Connecting and setting up your environment: warn about no backups

← Older revision		Revision as of 14:22, 23 October 2026
Line 36:		Line 36:
	To upload scripts or data files, you can use <code>scp</code> from your local computer (Mac or Linux); on Windows, you can get the Tectia SSH graphical client [https://www.cmu.edu/computing/services/endpoint/software/access.html free through CMU].		To upload scripts or data files, you can use <code>scp</code> from your local computer (Mac or Linux); on Windows, you can get the Tectia SSH graphical client [https://www.cmu.edu/computing/services/endpoint/software/access.html free through CMU].

	You can~~ ~~also connect through the [https://code.visualstudio.com/docs/remote/ssh Remote SSH feature of VS Code] if you like. This is useful to~~ ~~		You can also connect through the [https://code.visualstudio.com/docs/remote/ssh Remote SSH feature of VS Code] if you like. This is useful to

	*navigate the file system from a proper GUI and		*navigate the file system from a proper GUI and
	*modify code/files/folder in place if you are not familiar with the command line		*modify code/files/folder in place if you are not familiar with the command line
	Files uploaded to your home directory will be accessible on the head node and all compute nodes, so they can be freely used in compute jobs.		Files uploaded to your home directory will be accessible on the head node and all compute nodes, so they can be freely used in compute jobs.

			=== Danger! Files are not backed up ===
			Wright's storage cluster is '''not backed up.''' You may lose data if a disk fails. Therefore:

			* Keep your code backed up in another location (such as by pushing it to GitHub regularly)
			* Do not use Wright for long-term storage of important data. Download local copies, push it to HuggingFace, or sync it to your Google Drive
			* Consider using an online backup tool like [https://www.borgbackup.org/ Borg] or [https://www.tarsnap.com/ Tarsnap] to regularly back up your home directory

	=== Using Conda ===		=== Using Conda ===

Overleaf Git Integration

Ajshen — Sun, 18 Oct 2026 23:31:43 GMT

Sending new results to the paper

← Older revision		Revision as of 23:31, 18 October 2026
(2 intermediate revisions by the same user not shown)
Line 75:		Line 75:
	<!-- SCREENSHOT: Overleaf project Menu, with the "Sync → Git" entry highlighted. -->		<!-- SCREENSHOT: Overleaf project Menu, with the "Sync → Git" entry highlighted. -->
	[[File:Overleaf-menu-sync-git.png\|thumb\|center\|300px\|The Git entry in the Overleaf project menu.]]		[[File:Overleaf-menu-sync-git.png\|thumb\|center\|300px\|The Git entry in the Overleaf project menu.]]

	~~<!-- SCREENSHOT: The Git dialog showing the clone command (blur or crop the project ID if you prefer). -->~~
	~~[[File:Overleaf-git-clone-url.png\|thumb\|center\|500px\|The project's Git clone URL.]]~~

	=== Step 3: Clone the paper inside your experiment repository ===		=== Step 3: Clone the paper inside your experiment repository ===
Line 100:		Line 97:
	</syntaxhighlight>		</syntaxhighlight>

	~~<!-- SCREENSHOT: Terminal showing both `git status` outputs (outer repo clean, inner repo on master). -->~~
	~~[[File:Nested-clone-git-status.png\|thumb\|center\|600px\|The outer repository ignores <code>paper/</code>; the inner repository is independent.]]~~

	<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">		<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
Line 186:		Line 181:
	That's it. Refresh the Overleaf editor and recompile, and the new figures are there.		That's it. Refresh the Overleaf editor and recompile, and the new figures are there.

	~~<!-- SCREENSHOT: Overleaf file tree / editor right after a push, showing the updated figure (optionally with the History panel open). -->~~
	~~[[File:Overleaf-after-git-push.png\|thumb\|center\|600px\|Pushed figures appear in Overleaf immediately.]]~~

	<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">		<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">

File:Overleaf-menu-sync-git.png

Ajshen — Sun, 18 Oct 2026 23:29:33 GMT

Ajshen uploaded File:Overleaf-menu-sync-git.png

New page

File:Overleaf-git-token.png

Ajshen — Sun, 18 Oct 2026 23:29:17 GMT

Ajshen uploaded a new version of File:Overleaf-git-token.png

New page

Overleaf GitHub Integration

Ajshen — Sun, 18 Oct 2026 23:27:23 GMT

Ajshen moved page Overleaf GitHub Integration to Overleaf Git Integration

New page

[[Category:Typesetting]]

If your experiment code lives in a Git repository and your paper lives on Overleaf, you have probably done '''the upload dance''': rerun an experiment, hunt down the regenerated figure on disk, open Overleaf, delete the old file, upload the new one, and repeat for every figure and table that changed. It is slow, it is easy to leave a stale figure behind, and it leaves no record of which version of your code produced which figure in the paper.

Overleaf Premium's '''Git integration''' removes most of this busywork. Every Overleaf project can be cloned as an ordinary Git repository, with no GitHub account or extra repository required. This article describes one way to use it: cloning the Overleaf project '''inside''' your experiment repository, in a directory that the experiment repository ignores. Your analysis scripts then write figures and tables straight into the paper, and a single <code>git push</code> puts them on Overleaf.

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Important: Overleaf Premium is required'''<br>
Git integration is a paid Overleaf feature. Check whether you already have access through an institutional license before paying for it yourself. If you don't use Git yet, read up on the basics first, since this workflow assumes you are comfortable with <code>clone</code>, <code>commit</code>, <code>push</code>, and <code>pull</code>.
</div>

== How It Works ==
There are several ways to connect a code repository to an Overleaf project. In this one, the two repositories stay '''completely independent'''. The Overleaf project is cloned into a subdirectory (here called <code>paper/</code>), and that subdirectory is listed in the experiment repository's <code>.gitignore</code>. The experiment repository never records anything about the paper, and the paper never sees your experimental code. Your scripts simply write files into a folder that happens to be a different Git repository, one whose remote is Overleaf itself.

The final layout looks like this:

<pre>
my-experiments/ ← experiment repo
├── .gitignore ← contains "paper/"
├── src/
├── scripts/
│ └── make_figures.py ← writes into paper/figures and paper/tables
├── Makefile
└── paper/ ← SEPARATE git repo, ignored by the outer repo
├── .git/ ← remote: https://git.overleaf.com/<project-id>
├── main.tex
├── refs.bib
├── figures/ ← written by code
│ ├── coverage.pdf
│ └── PROVENANCE.txt ← which code version made these
└── tables/ ← written by code
└── results.tex
</pre>

Changes flow directly in both directions, with nothing in between:

<pre>
scripts/make_figures.py ──writes──▶ paper/figures, paper/tables
paper/ ──git push──▶ Overleaf
Overleaf ──git pull──▶ paper/
</pre>

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #d4edda; color: #155724; padding: 10px; text-align: left;" | Strengths
! style="width: 50%; background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Weaknesses
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* '''No More Uploading:''' Regenerated figures and tables reach the paper with one commit and one push, no manual file shuffling required.
* '''Instant Updates:''' A <code>git push</code> shows up in the Overleaf editor right away. There is no sync button to remember.
* '''Minimal Setup:''' No GitHub account, no extra repository, and no linking accounts. You need a token and a clone URL, and that's it.
* '''No Coupled Tracking:''' Unlike git submodules, you never need an extra "update the paper pointer" commit in your experiment repository every time the paper changes.
* '''Collaborator Friendly:''' Co-authors keep writing on Overleaf as usual. Nothing about their workflow changes.
| style="padding: 15px;" |
* '''Provenance Is Up to You:''' Because the repositories are not linked, you need to record which code produced which figure yourself. A small script (below) handles this.
* '''No Off-Site Copy:''' The paper lives only on Overleaf (and your local clones). If you want GitHub issues, pull-request reviews, or an independent backup, Overleaf's GitHub Synchronization is the better fit.
* '''Token Management:''' You need an Overleaf Git token on every machine you push from, including clusters.
* '''One More Thing to Clone:''' Anyone who wants to regenerate the paper's figures needs to clone the Overleaf project separately.
|-
| colspan="2" style="background-color: #e9ecef; text-align: center; padding: 10px;" | 🔗 '''[https://www.overleaf.com/learn/how-to/Git_integration Overleaf Documentation: Git Integration]'''
|}

== Setting It Up ==

=== Step 1: Generate a Git authentication token ===
Overleaf doesn't accept your account password over Git. In Overleaf, open '''Account Settings''', find the '''Git Integration''' section, and generate a token. Copy it somewhere safe right away, because Overleaf will only show it once.


[[File:Overleaf-git-token.png|thumb|center|600px|Generating an Overleaf Git authentication token.]]

=== Step 2: Find your project's clone URL ===
Open your paper in Overleaf, click '''Menu''' in the top left, and choose '''Git''' under the ''Sync'' section. The dialog shows a <code>git clone</code> command with your project's URL, which looks like <code>https://git.overleaf.com/<project-id></code>. The project ID is the same string that appears in your browser's address bar when the project is open.


[[File:Overleaf-menu-sync-git.png|thumb|center|300px|The Git entry in the Overleaf project menu.]]


[[File:Overleaf-git-clone-url.png|thumb|center|500px|The project's Git clone URL.]]

=== Step 3: Clone the paper inside your experiment repository ===
From the root of your experiment repository, tell Git to ignore the <code>paper/</code> directory '''before''' you clone into it:

<syntaxhighlight lang="bash">
cd my-experiments
echo "paper/" >> .gitignore
git add .gitignore
git commit -m "Ignore nested paper clone"

git clone https://git.overleaf.com/<project-id> paper
</syntaxhighlight>

When Git asks for credentials, enter <code>git</code> as the username and your '''token''' as the password. To avoid typing the token every time, let Git remember it with your system's credential helper (e.g. <code>osxkeychain</code> on macOS, <code>manager</code> on Windows). On shared machines, avoid the plain-text <code>store</code> helper.

Then check that the two repositories don't see each other:

<syntaxhighlight lang="bash">
git status # should NOT list paper/
git -C paper status # shows the Overleaf project, on branch master
</syntaxhighlight>


[[File:Nested-clone-git-status.png|thumb|center|600px|The outer repository ignores <code>paper/</code>; the inner repository is independent.]]

<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Warning: Don't skip the <code>.gitignore</code> entry'''<br>
Without it, a careless <code>git add .</code> in the experiment repository will register <code>paper/</code> as an "embedded repository," which confuses collaborators and anything else that clones your code. If this happens, <code>git rm --cached paper</code> undoes it.
</div>

=== Step 4: Point your code at the paper directory ===
Rather than hard-coding paths in every script, define the paper location once. Using an environment variable with a sensible default means the code still runs for people who haven't cloned the paper (their figures just land in an ignored folder).

<syntaxhighlight lang="python">
# src/paths.py
import os
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[1]
PAPER_DIR = Path(os.environ.get("PAPER_DIR", REPO_ROOT / "paper"))
FIG_DIR = PAPER_DIR / "figures"
TAB_DIR = PAPER_DIR / "tables"

FIG_DIR.mkdir(parents=True, exist_ok=True)
TAB_DIR.mkdir(parents=True, exist_ok=True)
</syntaxhighlight>

For '''figures''', save vector PDFs directly into the paper. Removing the creation timestamp means a figure that didn't actually change produces an identical file, so Git won't report a pointless change:

<syntaxhighlight lang="python">
import matplotlib.pyplot as plt
from src.paths import FIG_DIR

fig, ax = plt.subplots(figsize=(3.25, 2.4)) # match your template's column width
...
fig.savefig(FIG_DIR / "coverage.pdf", bbox_inches="tight",
metadata={"CreationDate": None})
</syntaxhighlight>

For '''tables''', write a LaTeX fragment rather than a full document:

<syntaxhighlight lang="python">
from src.paths import TAB_DIR

tex = df.to_latex(index=False, escape=True, float_format="%.3f")
(TAB_DIR / "results.tex").write_text(tex)
</syntaxhighlight>

and pull both into the paper as usual:

<syntaxhighlight lang="latex">
\includegraphics[width=\linewidth]{figures/coverage}
...
\input{tables/results}
</syntaxhighlight>

For '''numbers quoted in the text''', the same idea works. Have your code write LaTeX macros so the prose never goes stale:

<syntaxhighlight lang="python">
(TAB_DIR / "numbers.tex").write_text(
f"\\newcommand{{\\coverageNinetyFive}}{{{cov95:.1f}\\%}}\n"
)
</syntaxhighlight>

<syntaxhighlight lang="latex">
% preamble
\input{tables/numbers}
% body
Our intervals achieve \coverageNinetyFive{} empirical coverage.
</syntaxhighlight>

== Day-to-Day Workflow ==

=== Sending new results to the paper ===
After rerunning your experiments, commit and push from inside <code>paper/</code>:

<syntaxhighlight lang="bash">
python scripts/make_figures.py

cd paper
git pull # pick up any text edits made on Overleaf first
git add figures tables
git commit -m "Regenerate figures"
git push
</syntaxhighlight>

That's it. Refresh the Overleaf editor and recompile, and the new figures are there.


[[File:Overleaf-after-git-push.png|thumb|center|600px|Pushed figures appear in Overleaf immediately.]]

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Important: Always pull before you push'''<br>
Your co-authors are editing the same repository through the Overleaf editor. If anything changed on Overleaf since your last pull, your push will be rejected until you <code>git pull</code> and merge. As long as your code only touches <code>figures/</code> and <code>tables/</code>, these merges are automatic.
</div>

=== Recording provenance ===
Since the two repositories aren't linked, have your script record which code produced the figures. Overleaf's Git integration does not reliably preserve your local commit messages, so write the information into a '''file''' in the paper instead:

<syntaxhighlight lang="bash">
SHA=$(git rev-parse --short HEAD)
git diff --quiet || SHA="$SHA-dirty"
echo "Generated from my-experiments@$SHA on $(date -u +%Y-%m-%dT%H:%MZ)" > paper/figures/PROVENANCE.txt
</syntaxhighlight>

The <code>-dirty</code> suffix flags figures made from uncommitted code. Months later, opening <code>PROVENANCE.txt</code> (or its history in Overleaf) answers "where did these figures come from?"

=== Automating it with a Makefile ===
Once the steps above feel familiar, wrap them in a single command:

<syntaxhighlight lang="make">
PAPER := paper
SHA := $(shell git rev-parse --short HEAD)$(shell git diff --quiet || echo -dirty)

.PHONY: figures paper-sync

figures:
python scripts/make_figures.py

paper-sync: figures
git -C $(PAPER) pull --rebase
git -C $(PAPER) diff --quiet -- figures tables || \
echo "Generated from my-experiments@$(SHA) on $$(date -u +%Y-%m-%dT%H:%MZ)" > $(PAPER)/figures/PROVENANCE.txt
git -C $(PAPER) add figures tables
git -C $(PAPER) diff --cached --quiet || \
git -C $(PAPER) commit -m "Regenerate figures from my-experiments@$(SHA)"
git -C $(PAPER) push
</syntaxhighlight>

Now <code>make paper-sync</code> regenerates everything, pulls in your co-authors' edits, updates the provenance file only when a figure or table actually changed, skips the commit entirely if nothing changed, and pushes straight to Overleaf.

=== Avoiding conflicts ===
Conflicts are rare if every file has exactly one "owner":

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''<code>figures/</code> and <code>tables/</code> belong to your code.''' Never edit them by hand on Overleaf; the next regeneration will silently overwrite your changes. Change the formatting in the code that generates them instead.
</div>

<div style="background-color: #f8f9fa; border-left: 4px solid #228B22; padding: 15px; margin-bottom: 10px;">
'''<code>.tex</code> and <code>.bib</code> files belong to people.''' Write them in the Overleaf editor (or locally, then push), and always pull before you push figures.
</div>

== Why Not a Git Submodule? ==
Git submodules are the "official" way to put one repository inside another, so it is natural to ask why this workflow avoids them.

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="background-color: #e9ecef; padding: 10px; text-align: left;" |
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Gitignored Clone
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Git Submodule
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Experiment repo records the paper version''' || style="padding: 10px;" | No || style="padding: 10px;" | Yes (a pointer)
|-
| style="padding: 10px;" | '''Extra commit in experiment repo per paper change''' || style="padding: 10px;" | No || style="padding: 10px;" | Yes
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Collaborators need Overleaf credentials to clone the code''' || style="padding: 10px;" | No || style="padding: 10px;" | Yes, for a full clone
|-
| style="padding: 10px;" | '''Link between figure and code version''' || style="padding: 10px;" | Provenance file || style="padding: 10px;" | Automatic
|}

A submodule gives you exact, automatic provenance, but at a price. Every change to the paper, including every typo fix a co-author makes on Overleaf, needs a matching "bump the submodule" commit in your experiment repository. On top of that, anyone cloning your code with submodules would need an Overleaf token. For a paper that is edited daily, this usually isn't worth it. The gitignored clone trades automatic provenance for a one-line provenance file, which is plenty in practice.

== Variations ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Want a GitHub copy of the paper?''' Overleaf's GitHub Synchronization keeps the project mirrored in a GitHub repository, which you can clone into the gitignored directory in exactly the same way. You gain issues, pull-request reviews, and an off-site backup. The cost is a manual sync step, since Overleaf only exchanges changes with GitHub when someone clicks a button in the Overleaf menu.
</div>

<div style="background-color: #f8f9fa; border-left: 4px solid #FFD43B; padding: 15px; margin-bottom: 10px;">
'''Generating figures on a cluster:''' Clone the Overleaf project on the cluster as well, set up your token with a credential helper, and run <code>make paper-sync</code> there. Alternatively, point <code>PAPER_DIR</code> at a scratch directory on the cluster, copy the outputs back to your laptop, and push from there, so your token never leaves your own machine.
</div>

== Common Pitfalls ==
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Things to Watch Out For
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px;" |
* '''Rejected pushes:''' Someone edited the paper on Overleaf since your last pull. Run <code>git pull</code>, then push again. Never force-push to Overleaf.
* '''Authentication failures:''' The username is literally <code>git</code>, and the password is your token, not your Overleaf password. If a token stops working, generate a new one and update your credential helper.
* '''Working on branches:''' Overleaf only knows about <code>master</code>. You can branch locally, but only commits merged into <code>master</code> can be pushed.
* '''Bloating the project:''' PNGs and timestamped PDFs change on every run. Prefer vector PDFs with the timestamp removed, and only commit figures that actually changed.
* '''Overleaf project limits:''' Overleaf limits project size and file counts. Keep raw outputs, checkpoints, and intermediate data in the experiment repository (or out of Git entirely); only put paper-ready figures and tables in <code>paper/</code>.
* '''Leaking tokens:''' Never paste the token into the clone URL in a shared script or commit it anywhere. Let a credential helper store it.
|}

<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
'''Note:''' This is just one of several ways to connect your code and your paper. If you want your paper on GitHub, try GitHub Synchronization instead; if you want airtight provenance, a submodule may be worth the extra commits.
</div>

File:Overleaf-git-token.png

Ajshen — Sun, 18 Oct 2026 23:27:02 GMT

Ajshen uploaded File:Overleaf-git-token.png

New page

Overleaf GitHub Integration

Ajshen — Sun, 18 Oct 2026 23:24:07 GMT

Show changes

Overleaf

Ajshen — Sun, 18 Oct 2026 23:12:50 GMT

Common Pitfalls

← Older revision		Revision as of 23:12, 18 October 2026
(One intermediate revision by the same user not shown)
Line 1:		Line 1:
	<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->		<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->
	[[Category:Typesetting]]		[[index.php?title=Category:Typesetting]]

	'''[https://www.overleaf.com Overleaf]''' is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.		'''[https://www.overleaf.com Overleaf]''' is a browser-based LaTeX editor. It gives you a full TeX Live installation, a live PDF preview, and Google-Docs-style collaboration, all without installing anything on your machine. For most papers written with co-authors, it has become the default place where the writing actually happens.
Line 104:		Line 104:

	<div style="background-color: #f8f9fa; border-left: 4px solid #228B22; padding: 15px; margin-bottom: 10px;">		<div style="background-color: #f8f9fa; border-left: 4px solid #228B22; padding: 15px; margin-bottom: 10px;">
	'''Git and GitHub sync (Premium):''' Every Premium project can be cloned directly with Git, and can also be synchronized with a GitHub repository. This lets you edit locally in your own editor, and lets your analysis code write figures and tables straight into the paper. See [[Overleaf GitHub ~~Sync\|Syncing Experiment Code with Overleaf via GitHub~~]] for a complete workflow. <!-- TODO: fix this link to match the actual title of the GitHub sync article -->		'''Git and GitHub sync (Premium):''' Every Premium project can be cloned directly with Git, and can also be synchronized with a GitHub repository. This lets you edit locally in your own editor, and lets your analysis code write figures and tables straight into the paper. See [[Overleaf GitHub Integration]] for a complete workflow. <!-- TODO: fix this link to match the actual title of the GitHub sync article -->
	</div>		</div>

Line 134:		Line 134:

	<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">		<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
	'''Note:''' Overleaf is a writing tool, not a research workflow by itself. Once you're comfortable with the basics, see [[Overleaf GitHub ~~Sync\|Syncing Experiment Code with Overleaf via GitHub~~]] for a way to keep your figures and tables in sync with your code. <!-- TODO: fix this link to match the actual title of the GitHub sync article -->		'''Note:''' Overleaf is a writing tool, not a research workflow by itself. Once you're comfortable with the basics, see [[Overleaf GitHub Integration]] for a way to keep your figures and tables in sync with your code. <!-- TODO: fix this link to match the actual title of the GitHub sync article -->
	</div>		</div>

File:Overleaf-history-view.png

Ajshen — Sun, 18 Oct 2026 23:11:25 GMT

Ajshen uploaded File:Overleaf-history-view.png

New page

File:Overleaf-review-panel.png

Ajshen — Sun, 18 Oct 2026 23:10:04 GMT

Ajshen uploaded File:Overleaf-review-panel.png

New page

File:Overleaf-menu-settings dialogue.png

Ajshen — Sun, 18 Oct 2026 23:08:55 GMT

Ajshen uploaded File:Overleaf-menu-settings dialogue.png

New page

Overleaf

Ajshen — Sun, 18 Oct 2026 23:08:28 GMT

Step 4: Check the project settings

← Older revision		Revision as of 23:08, 18 October 2026
Line 69:		Line 69:

	<!-- SCREENSHOT: The Overleaf project Menu with the Compiler, TeX Live version, and Main document settings highlighted. -->		<!-- SCREENSHOT: The Overleaf project Menu with the Compiler, TeX Live version, and Main document settings highlighted. -->
	[[File:Overleaf-menu-settings.png\|thumb\|center\|300px\|Compiler and main-document settings in the project menu.]]		[[File:Overleaf-menu-settings.png\|thumb\|center\|300px\|Where to find the settings menu.]]
			[[File:Overleaf-menu-settings_dialogue.png\|thumb\|center\|300px\|Compiler and main-document settings in the project menu.]]

	== Working With Co-Authors ==		== Working With Co-Authors ==

File:Overleaf-menu-settings.png

Ajshen — Sun, 18 Oct 2026 23:07:51 GMT

Ajshen uploaded File:Overleaf-menu-settings.png

New page

File:Overleaf-editor-overview.png

Ajshen — Sun, 18 Oct 2026 23:05:45 GMT

Ajshen uploaded File:Overleaf-editor-overview.png

New page

File:Overleaf-new-project-menu.png

Ajshen — Sun, 18 Oct 2026 23:04:45 GMT

Ajshen uploaded File:Overleaf-new-project-menu.png

New page

Category:Typesetting

Ajshen — Sun, 18 Oct 2026 23:03:18 GMT

Created blank page

New page

Overleaf

Ajshen — Sun, 18 Oct 2026 23:03:09 GMT

Show changes

Overleaf GitHub Integration

Ajshen — Sun, 18 Oct 2026 22:51:47 GMT

Created page with " XX If your experiment code lives in a GitHub repository and your paper lives on Overleaf, you have probably done '''the upload dance''': rerun an experiment, hunt down the regenerated figure on disk, open Overleaf, delete the old file, upload the new one, and repeat for every figure and table that changed. It is slow, it is easy to le..."

New page

[[Category:Beginner's_Guide_Implementation|XX]]

If your experiment code lives in a GitHub repository and your paper lives on Overleaf, you have probably done '''the upload dance''': rerun an experiment, hunt down the regenerated figure on disk, open Overleaf, delete the old file, upload the new one, and repeat for every figure and table that changed. It is slow, it is easy to leave a stale figure behind, and it leaves no record of which version of your code produced which figure in the paper.

Overleaf Premium's '''GitHub Synchronization''' feature removes most of this busywork. This article describes one particular way to use it: cloning the paper's repository '''inside''' your experiment repository, in a directory that the experiment repository ignores. Your analysis scripts then write figures and tables straight into the paper, and a single push sends them to Overleaf.

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Important: Overleaf Premium is required'''<br>
GitHub Synchronization is a paid Overleaf feature. Check whether you already have access through an institutional license before paying for it yourself. If you don't use Git yet, read up on the basics first, since this workflow assumes you are comfortable with <code>clone</code>, <code>commit</code>, <code>push</code>, and <code>pull</code>.
</div>

== How It Works ==
There are several ways to connect a code repository to an Overleaf project. In this one, the two repositories stay '''completely independent'''. The paper repository is cloned into a subdirectory (here called <code>paper/</code>), and that subdirectory is listed in the experiment repository's <code>.gitignore</code>. The experiment repository never records anything about the paper, and the paper repository never sees your experimental code. Your scripts simply write files into a folder that happens to be a different Git repository.

The final layout looks like this:

<pre>
my-experiments/ ← experiment repo (github.com/you/my-experiments)
├── .gitignore ← contains "paper/"
├── src/
├── scripts/
│ └── make_figures.py ← writes into paper/figures and paper/tables
├── Makefile
└── paper/ ← SEPARATE git repo, ignored by the outer repo
├── .git/ ← points to github.com/you/my-paper
├── main.tex
├── refs.bib
├── figures/ ← written by code
│ └── coverage.pdf
└── tables/ ← written by code
└── results.tex
</pre>

Generated figures and tables flow from your code to Overleaf, and prose written on Overleaf flows back to your local copy:

<pre>
scripts/make_figures.py ──writes──▶ paper/figures, paper/tables
paper/ ──git push──▶ GitHub (my-paper) ──"Pull GitHub changes"──▶ Overleaf
Overleaf ──"Push Overleaf changes"──▶ GitHub (my-paper) ──git pull──▶ paper/
</pre>

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #d4edda; color: #155724; padding: 10px; text-align: left;" | Strengths
! style="width: 50%; background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Weaknesses
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* '''No More Uploading:''' Regenerated figures and tables reach the paper with one commit and one push, no manual file shuffling required.
* '''Clean Histories:''' Paper edits never clutter your code history, and code changes never clutter your paper history.
* '''No Coupled Tracking:''' Unlike git submodules, you never need an extra "update the paper pointer" commit in your experiment repository every time the paper changes.
* '''Collaborator Friendly:''' Co-authors can keep writing on Overleaf as usual. Nothing about their workflow changes.
| style="padding: 15px;" |
* '''Sync Is Manual:''' Overleaf does not watch GitHub. Someone has to click a button in Overleaf to pull new changes in (and to push Overleaf edits out).
* '''Provenance Is Up to You:''' Because the repositories are not linked, the only record of which code produced a figure is whatever you write in the paper's commit messages. A small script (below) handles this for you.
* '''One More Thing to Clone:''' Anyone who wants to regenerate the paper's figures needs to clone the paper repository separately.
|-
| colspan="2" style="background-color: #e9ecef; text-align: center; padding: 10px;" | 🔗 '''[https://www.overleaf.com/learn/how-to/GitHub_Synchronization Overleaf Documentation: GitHub Synchronization]'''
|}

== Setting It Up ==

=== Step 1: Link Overleaf to GitHub ===
In Overleaf, open '''Account Settings''' and find the GitHub entry under the project synchronization section. Click '''Link''' and authorize Overleaf in the GitHub dialog that pops up.


[[File:Overleaf-account-settings-github-link.png|thumb|center|600px|Linking a GitHub account from Overleaf's account settings.]]

=== Step 2: Create a GitHub repository from your Overleaf project ===
Open your paper in Overleaf, click '''Menu''' in the top left, and choose '''GitHub''' under the ''Sync'' section. Select '''Create a GitHub repository''', give it a name (e.g. <code>my-paper</code>), and make it private. Overleaf then pushes the current contents of your project to the new repository.


[[File:Overleaf-menu-sync-github.png|thumb|center|300px|The GitHub entry in the Overleaf project menu.]]


[[File:Overleaf-create-github-repo.png|thumb|center|500px|Creating the paper repository from Overleaf.]]

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Tip: Already have the paper on GitHub?'''<br>
You can go the other direction instead. In Overleaf, choose '''New Project → Import from GitHub''' and select your existing repository.
</div>

=== Step 3: Clone the paper inside your experiment repository ===
From the root of your experiment repository, tell Git to ignore the <code>paper/</code> directory '''before''' you clone into it:

<syntaxhighlight lang="bash">
cd my-experiments
echo "paper/" >> .gitignore
git add .gitignore
git commit -m "Ignore nested paper clone"

git clone git@github.com:you/my-paper.git paper
</syntaxhighlight>

Then check that the two repositories don't see each other:

<syntaxhighlight lang="bash">
git status # should NOT list paper/
git -C paper status # shows the paper repo, on its own branch
</syntaxhighlight>


[[File:Nested-clone-git-status.png|thumb|center|600px|The outer repository ignores <code>paper/</code>; the inner repository is independent.]]

<div style="background-color: #f8d7da; border-left: 5px solid #721c24; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Warning: Don't skip the <code>.gitignore</code> entry'''<br>
Without it, a careless <code>git add .</code> in the experiment repository will register <code>paper/</code> as an "embedded repository," which confuses collaborators and anything else that clones your code. If this happens, <code>git rm --cached paper</code> undoes it.
</div>

=== Step 4: Point your code at the paper directory ===
Rather than hard-coding paths in every script, define the paper location once. Using an environment variable with a sensible default means the code still runs for people who haven't cloned the paper (their figures just land in an ignored folder).

<syntaxhighlight lang="python">
# src/paths.py
import os
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[1]
PAPER_DIR = Path(os.environ.get("PAPER_DIR", REPO_ROOT / "paper"))
FIG_DIR = PAPER_DIR / "figures"
TAB_DIR = PAPER_DIR / "tables"

FIG_DIR.mkdir(parents=True, exist_ok=True)
TAB_DIR.mkdir(parents=True, exist_ok=True)
</syntaxhighlight>

For '''figures''', save vector PDFs directly into the paper. Removing the creation timestamp means a figure that didn't actually change produces an identical file, so Git won't report a pointless change:

<syntaxhighlight lang="python">
import matplotlib.pyplot as plt
from src.paths import FIG_DIR

fig, ax = plt.subplots(figsize=(3.25, 2.4)) # match your template's column width
...
fig.savefig(FIG_DIR / "coverage.pdf", bbox_inches="tight",
metadata={"CreationDate": None})
</syntaxhighlight>

For '''tables''', write a LaTeX fragment rather than a full document:

<syntaxhighlight lang="python">
from src.paths import TAB_DIR

tex = df.to_latex(index=False, escape=True, float_format="%.3f")
(TAB_DIR / "results.tex").write_text(tex)
</syntaxhighlight>

and pull both into the paper as usual:

<syntaxhighlight lang="latex">
\includegraphics[width=\linewidth]{figures/coverage}
...
\input{tables/results}
</syntaxhighlight>

For '''numbers quoted in the text''', the same idea works. Have your code write LaTeX macros so the prose never goes stale:

<syntaxhighlight lang="python">
(TAB_DIR / "numbers.tex").write_text(
f"\\newcommand{{\\coverageNinetyFive}}{{{cov95:.1f}\\%}}\n"
)
</syntaxhighlight>

<syntaxhighlight lang="latex">
% preamble
\input{tables/numbers}
% body
Our intervals achieve \coverageNinetyFive{} empirical coverage.
</syntaxhighlight>

== Day-to-Day Workflow ==

=== Sending new results to the paper ===
After rerunning your experiments, commit and push from inside <code>paper/</code>:

<syntaxhighlight lang="bash">
python scripts/make_figures.py

cd paper
git pull # pick up any text edits pushed from Overleaf first
git add figures tables
git commit -m "Regenerate figures from my-experiments@$(git -C .. rev-parse --short HEAD)"
git push
</syntaxhighlight>

Then, in Overleaf, open '''Menu → GitHub''' and click '''Pull GitHub changes into Overleaf'''.


[[File:Overleaf-pull-github-changes.png|thumb|center|500px|Bringing the regenerated figures into Overleaf.]]

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Important: Overleaf does not sync automatically'''<br>
Overleaf only picks up changes from GitHub when someone clicks the pull button, and only sends its own changes to GitHub when someone clicks the push button. Forgetting the pull is by far the most common reason the paper still shows old figures.
</div>

The commit message above includes the short hash of your experiment repository. Since the two repositories aren't linked, this message is your record of which code produced which figure. Running <code>git log -- figures/coverage.pdf</code> inside <code>paper/</code> will answer "where did this figure come from?" months later.

=== Automating it with a Makefile ===
Once the steps above feel familiar, wrap them in a single command:

<syntaxhighlight lang="make">
PAPER := paper
SHA := $(shell git rev-parse --short HEAD)$(shell git diff --quiet || echo -dirty)

.PHONY: figures paper-sync

figures:
python scripts/make_figures.py

paper-sync: figures
git -C $(PAPER) pull --rebase
git -C $(PAPER) add figures tables
git -C $(PAPER) diff --cached --quiet || \
git -C $(PAPER) commit -m "Regenerate figures from my-experiments@$(SHA)"
git -C $(PAPER) push
@echo "Now click 'Pull GitHub changes into Overleaf' in the Overleaf GitHub menu."
</syntaxhighlight>

Now <code>make paper-sync</code> regenerates everything, skips the commit if nothing actually changed, marks the commit <code>-dirty</code> if your experiment code had uncommitted changes, and reminds you to pull in Overleaf.

=== When co-authors edit on Overleaf ===
Before regenerating figures locally, push any Overleaf edits out to GitHub ('''Menu → GitHub → Push Overleaf changes to GitHub''') so that the <code>git pull</code> in <code>paper/</code> picks them up.


[[File:Overleaf-push-to-github.png|thumb|center|500px|Sending Overleaf edits back to GitHub.]]

=== Avoiding conflicts ===
Conflicts are rare if every file has exactly one "owner":

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''<code>figures/</code> and <code>tables/</code> belong to your code.''' Never edit them by hand on Overleaf; the next regeneration will silently overwrite your changes. Change the formatting in the code that generates them instead.
</div>

<div style="background-color: #f8f9fa; border-left: 4px solid #228B22; padding: 15px; margin-bottom: 10px;">
'''<code>.tex</code> and <code>.bib</code> files belong to people.''' Write them on Overleaf (or locally, then push), and always pull before you push figures.
</div>

== Why Not a Git Submodule? ==
Git submodules are the "official" way to put one repository inside another, so it is natural to ask why this workflow avoids them.

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="background-color: #e9ecef; padding: 10px; text-align: left;" |
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Gitignored Clone
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Git Submodule
! style="background-color: #e9ecef; padding: 10px; text-align: left;" | Git Subtree
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Experiment repo records the paper version''' || style="padding: 10px;" | No || style="padding: 10px;" | Yes (a pointer) || style="padding: 10px;" | Yes (full history)
|-
| style="padding: 10px;" | '''Extra commit in experiment repo per paper change''' || style="padding: 10px;" | No || style="padding: 10px;" | Yes || style="padding: 10px;" | Yes
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Paper history mixed into code history''' || style="padding: 10px;" | No || style="padding: 10px;" | No || style="padding: 10px;" | Yes
|-
| style="padding: 10px;" | '''Special clone instructions for collaborators''' || style="padding: 10px;" | No || style="padding: 10px;" | <code>--recurse-submodules</code> || style="padding: 10px;" | No
|- style="background-color: #f8f9fa;"
| style="padding: 10px;" | '''Link between figure and code version''' || style="padding: 10px;" | Commit message || style="padding: 10px;" | Automatic || style="padding: 10px;" | Automatic
|}

A submodule gives you exact, automatic provenance, but at a price: every change to the paper, including every typo fix a co-author pushes from Overleaf, needs a matching "bump the submodule" commit in your experiment repository. For a paper that is edited daily, that noise usually isn't worth it. The gitignored clone trades automatic provenance for a scripted commit message, which is plenty in practice.

== Variations ==

<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Skip GitHub with Overleaf's Git integration:''' Overleaf Premium also lets you clone a project directly (<code>git clone https://git.overleaf.com/<project-id></code>, using a Git token generated in Account Settings). Clone that into the gitignored directory instead, and a <code>git push</code> lands in Overleaf immediately with no pull button. The catch is that you no longer get a GitHub copy of the paper for issues, reviews, or backups.
</div>

<div style="background-color: #f8f9fa; border-left: 4px solid #FFD43B; padding: 15px; margin-bottom: 10px;">
'''Generating figures on a cluster:''' Clone the paper repository on the cluster as well and run <code>make paper-sync</code> there. Alternatively, point <code>PAPER_DIR</code> at a scratch directory on the cluster, copy the outputs back to your laptop, and push from there.
</div>

== Common Pitfalls ==
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Things to Watch Out For
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px;" |
* '''Forgetting the Overleaf pull:''' Your figures are on GitHub, but Overleaf still shows the old ones. The reminder in the Makefile helps.
* '''Pushing from both sides at once:''' If Overleaf has unpushed edits and GitHub has new figures, Overleaf has to merge them. Push from Overleaf first, pull locally, then push your figures.
* '''Bloating the paper repository:''' PNGs and timestamped PDFs change on every run. Prefer vector PDFs with the timestamp removed, and only commit figures that actually changed.
* '''Overleaf project limits:''' Overleaf limits project size and file counts. Keep raw outputs, checkpoints, and intermediate data in the experiment repository (or out of Git entirely); only put paper-ready figures and tables in <code>paper/</code>.
* '''Working on branches:''' Overleaf only syncs one branch. Stick to the default branch inside <code>paper/</code>; anything on another branch won't show up in Overleaf.
|}

<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
'''Note:''' This is just one of several ways to connect your code and your paper. If the manual pull button bothers you, try the Git integration variation above; if you want airtight provenance, a submodule may be worth the extra commits.
</div>