← Back to all topics
05 · Part 2 — Personal Setup Best Practices

File Management

OpenCode produces three distinct types of files, and each one needs to be handled differently. This page explains what each type is, what you need to do about it, and how to get set up — without any technical knowledge required.

The core idea: Work locally, back up to GitHub. Files stay on your machine so OpenCode can read them instantly. GitHub is the safety net — not the place you work from. Setting this up takes a few minutes once, then it runs automatically every hour.

Three kinds of files — three different situations

Everything you work with in OpenCode falls into one of three categories. They behave very differently and need different treatment.

📁

Working files

Context packs, playbooks, project notes, meeting transcripts, outputs. Everything you create and use day to day.

One-time setup, then automatic
⚙️

OpenCode config

Your MCP connections, global instructions, custom commands, and personal settings. Small but took time to build.

One-time setup, then automatic
💬

Session history

Every conversation you've had with OpenCode — including anything sensitive or private you've discussed or pasted in.

Local only — never cloud

Working files — set up hourly GitHub sync

Your working files need to be connected to a GitHub repository so they back up automatically. This is a one-time setup — once it's done, an hourly sync runs silently in the background.

What the setup does:

  1. Creates a private GitHub repository to hold your files — only you can access it.
  2. Connects your working folder on your Mac to that repository.
  3. Schedules an hourly sync that pushes any changes to GitHub automatically.

You don't need to understand how any of that works. Just ask OpenCode to do it:

Copy this prompt "Set up hourly GitHub backups for my OpenCode working folder. Create a private repository, connect my folder to it, and configure the sync to run automatically every hour."

Once it's running, you never need to think about it again. There's no manual backup command — it happens on a schedule.

OpenCode config — back it up once

Your OpenCode configuration is a separate folder that holds everything you've customised: which tools are connected (MCPs), your global instructions, and any personal commands. If your laptop died today, you'd need to rebuild all of this from scratch.

The fix is exactly the same as for working files — connect this folder to its own private GitHub repository. Once connected, it syncs automatically alongside everything else.

Copy this prompt "Back up my OpenCode config folder to a new private GitHub repository and add it to my hourly sync."
Already done? If you've set up OpenCode with someone's help, this may already be configured. Ask OpenCode: "Is my config folder being backed up to GitHub?" — it can check in seconds.

Session history — keep it local

Every conversation you have with OpenCode is stored as a transcript on your machine. This can include sensitive content — internal project details, customer context, anything you've pasted into a session.

Never send session history to a cloud service. Not GitHub, not OneDrive, not Google Drive, not iCloud. The transcripts live in a local folder that the hourly sync deliberately skips. If you use Time Machine or another local backup tool, they'll be covered automatically as part of your regular Mac backup.

You don't need to do anything to set this up — the right behaviour is already the default. Just make sure Time Machine (or equivalent) is running.

What to do today

  1. Set up working file sync. Ask OpenCode: "Are my working folders syncing to GitHub hourly? If not, set that up for me."
  2. Back up your config. Ask OpenCode: "Is my OpenCode config folder backed up to GitHub? If not, set that up."
  3. Check Time Machine. Open Time Machine on your Mac and confirm the last backup completed recently. This covers your session history and everything else on your machine.

The technical details — git, launchd, auto-sync scripts — are intentionally not covered here. If you want to understand or customise your setup, ask OpenCode to walk you through it.