Backlot

Your private workspace for public repos.

Backlot gives each project repo a local .backlot/ directory for private notes, agent state, prompts, drafts, scratch files, and local scripts without putting that material in the project repo's Git history.

One private archive. Many projects. No nested Git repo sprawl.

Contents

• Why Backlot?
• Install
• Quickstart
• Syncing Across Machines
• How It Works
• Directory Layout
• Using Backlot With LLMs And Agents
• Commands
• Safety Model
• Cleanup
• Limitations
• FAQ

Why Backlot?

Project context tends to collect beside the code: notes, LLM memory, prompts, roadmap drafts, local scripts, experiments, and half-formed thoughts. That context is useful precisely because it lives near the work, but it should not end up in the repo's history by accident.

Backlot keeps that private workspace close to the project while storing it in a separate Git repo you control. It works for open source repos, private company repos, and anything that might become public later.

Install

Homebrew:

brew install massivemoose/tap/backlot

Manual download:

1. Download the archive for your OS and architecture from the GitHub Releases page.

2. Verify it against checksums.txt:

   shasum -a 256 -c checksums.txt

3. Place the backlot binary somewhere on your PATH.

Install into your Go binary path:

go install github.com/massivemoose/backlot@latest

Build from source:

go build -o backlot .

Quickstart

Start from an existing project repo that has an origin remote:

backlot init
cd ~/code/my-project
git remote get-url origin
backlot attach

Your private workspace now lives at .backlot/ inside the project repo and is stored under ~/.backlot. Backlot uses your project repo's origin URL to choose a stable archive path such as github.com/you/my-project.

To back it up or use it across machines, create an empty private repo named backlot-archive on GitHub or your Git host. Do not initialize that repo with a README, license, or .gitignore. Then add it as the archive remote:

backlot init --remote git@github.com:you/backlot-archive.git
backlot sync -m "Initial Backlot archive"

Use init --remote for first-machine setup. If you want to work on another machine, clone the existing archive and attach your project repo again:

backlot clone git@github.com:you/backlot-archive.git
cd ~/code/my-project
backlot attach

For normal setup, you should not need to modify ~/.backlot directly.

Syncing Across Machines

backlot sync is a two-way Git sync for the private archive. It commits local private changes, fetches remote archive changes, rebases local commits when needed, and pushes the result.

Run it before switching machines and after starting work on another machine:

backlot sync

If two machines edit the same private file, Git may report a conflict. Backlot will stop and point at the conflicted files through your project link, such as .backlot/notes.md. Resolve the conflict in .backlot/, then run:

backlot sync --continue

To abandon the interrupted sync and return the archive to its previous state, run:

backlot sync --abort

Conflict resolution is manual for now so Backlot does not guess which private notes to keep.

How It Works

Backlot creates a .backlot symlink in the repo you are working in:

~/code/my-project/.backlot -> ~/.backlot/github.com/you/my-project

The target lives inside one central private archive, defaulting to ~/.backlot. Backlot adds local ignore entries for .backlot to .git/info/exclude, so the project repo ignores the private workspace without changing tracked files.

The archive path is based on the repo's origin remote. For example:

git@github.com:you/my-project.git
=> github.com/you/my-project

Directory Layout

The first time Backlot creates a private workspace for a project, it looks like this:

~/code/my-project/
  README.md
  src/
  .backlot -> ~/.backlot/github.com/you/my-project

~/.backlot/
  github.com/you/my-project/
    notes.md
    llm/
    scratch/

notes.md, llm/, and scratch/ are starter files only. Rename them, delete them, or add your own structure. Backlot does not enforce a layout inside a project's private workspace, and later backlot attach runs will not recreate starter files you removed.

Custom Starters

Create your own ~/.backlot/.starter/ to customize new project workspaces:

~/.backlot/
  .starter/
    notes.md
    roadmap.md
    llm/
      agent_state.md
      prompts.md
    scripts/

When Backlot creates a project private folder for the first time, it copies the contents of .starter/ into that folder. The copy is literal: no variables, no template rendering, and no automatic re-application. If .starter/ exists but is empty, new project folders start with only Backlot's .backlot-project metadata marker.

To add new starter paths to project workspaces that already exist, run:

backlot starter apply

This applies the current .starter/ to marked project workspaces in the local Backlot archive. It only creates missing files and directories. Existing paths are never overwritten, deleted, chmodded, or re-rendered. Use backlot starter apply --dry-run to preview the additions.

.backlot-project is Backlot-owned metadata used to find project workspaces. Do not put it in .starter/; backlot attach manages it automatically.

Using Backlot With LLMs And Agents

Backlot is useful as a local memory space for coding agents. Add something like this to AGENTS.md, CLAUDE.md, or your tool's project instructions:

Use `.backlot/` for private project context, notes, drafts, prompts, and agent state.
Read `.backlot/notes.md` and relevant files under `.backlot/llm/` when starting work.
Do not copy private `.backlot/` content into commits, PRs, issues, or public docs unless explicitly asked.

One simple layout:

.backlot/
  notes.md
  roadmap.md
  llm/
    agent_state.md
    prompts.md
  scratch/
    experiments.md
    local-scripts/

The structure is yours. Backlot only provides the private place to keep it.

Agent Sandboxes

Backlot uses a .backlot symlink that points into your private Backlot archive, usually under ~/.backlot. Some coding agents enforce filesystem permissions on the resolved symlink target, so AGENTS.md or CLAUDE.md can tell the agent to use .backlot/ but cannot grant access by itself.

If an agent asks for permission when reading or editing .backlot/, configure that agent to trust your Backlot archive root. See Using Backlot With Coding Agents, or run:

backlot agents setup

Commands

backlot help
backlot agents setup [--root PATH] [--tool codex|claude] [--apply]
backlot init [--root PATH] [--remote URL]
backlot clone <archive-url> [--root PATH]
backlot attach [--root PATH]
backlot detach [--root PATH]
backlot starter apply [--root PATH] [--dry-run]
backlot status [--root PATH]
backlot sync [--root PATH] [-m MESSAGE]
backlot sync [--root PATH] --continue
backlot sync [--root PATH] --abort
backlot protect
backlot doctor [--root PATH]
backlot version

• help shows this help.
• agents setup previews or applies coding-agent sandbox configuration.
• init creates or configures the local Backlot archive.
• clone clones an existing Backlot archive on a new machine.
• attach creates .backlot for the current repo.
• detach removes the current repo's Backlot symlink and local exclude entries.
• starter apply adds missing custom starter paths to marked project workspaces.
• status shows the current repo's Backlot state.
• sync pulls, commits, rebases, and pushes the private archive; --continue and --abort recover interrupted rebase conflicts.
• protect installs a local pre-commit guard for .backlot.
• doctor diagnoses setup issues.
• version prints build metadata.

Backlot root resolution order:

1. --root
2. BACKLOT_ROOT
3. ~/.backlot

Safety Model

• Backlot writes local ignore rules to .git/info/exclude, not .gitignore.
• Backlot does not commit to your project repo.
• Backlot does not stage files in your project repo.
• Backlot does not push from your project repo.
• Backlot only syncs private archive contents when you run backlot sync.
• Backlot does not encrypt files.

Why not .gitignore?

.gitignore is usually tracked. Writing to it would mutate the project repo and could leak Backlot-specific setup into shared history.

.git/info/exclude is local to your clone. Backlot uses it so .backlot stays ignored on your machine without changing files that belong to the project.

Privacy

Private files stay local until you run backlot sync. When you sync, Backlot commits and pushes the contents of your Backlot archive to the origin remote configured for that archive. Use a private remote for anything sensitive.

Cleanup

To disconnect Backlot from a repo, run:

backlot detach

This removes the managed .backlot symlink from the current repo and removes Backlot's local exclude entries from .git/info/exclude. It does not delete your private archive or any project notes.

If you intentionally want to remove the entire private archive from your machine, delete ~/.backlot yourself after detaching the repos you care about. Deleting ~/.backlot does not automatically clean up .backlot symlinks in attached repos; those links become broken until you remove them.

Limitations

• macOS and Linux are supported.
• Windows is not currently supported.
• No encryption yet.
• No daemon.
• No hosted sync.
• Requires Git.
• Requires a Git remote origin for project repos in the MVP.

FAQ

Can I use Backlot with private repos?

Yes. Backlot is useful for any repo where you want private notes or agent state beside the code without putting that context in the repo's history.

Does Backlot commit to my project repo?

No. Backlot never runs git add, git commit, or git push in your project repo. backlot sync runs Git commands inside the Backlot archive.

What if .backlot already exists?

Backlot refuses to overwrite a .backlot file, directory, or symlink it does not manage. Move the existing path before running backlot attach.

Can I use multiple Backlot archives?

Yes. Use --root PATH for one command or set BACKLOT_ROOT for a shell session.

Can I choose my own structure inside .backlot?

Yes. Backlot creates a few starter files only when it creates a project workspace for the first time, but it does not enforce their layout.