You were halfway through a refactor on your work laptop. Now you are on your home desktop, the code is pulled, and the new assistant session asks what the project is. It suggests the approach you ruled out on Tuesday. The code travelled. The context did not.

This happens because most of what makes an AI coding session useful never lives in tracked files. It sits in a chat history on one machine, in a note on your desktop, or in your head. Git moves the code well. It was never meant to move the reasoning around it.

This guide shows what to carry between machines, what to leave behind, and a short routine for both ends of the switch. It works with plain files and any assistant.

What stays behind when you switch machines

Before fixing the problem, list what you lose. On a typical switch, these things do not come with you:

  • Uncommitted work. The half-finished change you did not want in history yet.
  • Untracked notes. A TODO.md or notes.txt you kept out of the repo on purpose.
  • Your assistant's local history. The conversation where you and the assistant worked out the plan is stored on the machine where it happened.
  • Instructions in ignored files. Some people keep a personal instructions file out of git. It stays on the old machine.
  • The current state in your head. Which step of the plan you are on, what you already tried, what broke.
  • Local environment. .env files, keys and local config. These should stay behind, and we will come back to them.

The first five are context. The last one is configuration and secrets. Treat them differently.

Before you leave: a ten-minute handoff note

The cheapest fix is a note you write for your future self on the other machine. Write it at the end of the session, while you still remember what matters. Keep it in the project folder, not in a chat or an app.

A simple file such as .prjcontext/memory/current-state.md works well:

# Current state (updated before switching machines)

## Where I am
Refactoring the billing module into three services.
Done: invoice service extracted, tests pass.
Next: move the tax calculation out of `billing/core.py`.

## Decisions made this week
- Keep the old API shape until the mobile app ships its update.
- Rejected: one big "payments" service. Too many unrelated changes in one place.

## Open questions
- Should rounding happen per line or per invoice? Ask Sam.

## Do not do
- Do not rename `InvoiceLine`. The export job depends on the name.

Four headings are enough: where you are, what you decided, what is open, what to avoid. The "do not do" list matters most with an assistant. It is the part a fresh session is most likely to get wrong.

If a decision will outlive this week, give it its own record. The article on lightweight decision records shows a format that takes five minutes.

Keep context in the project folder, not in your tools

A note only helps if it travels with the code. The rule is simple: if the next session needs it, it lives inside the project folder.

A layout that keeps context separate from source, but beside it:

my-project/
  CLAUDE.md                     # instructions Claude Code reads
  AGENTS.md                     # instructions many other coding agents read
  src/
  tests/
  .prjcontext/
    instructions/               # longer instructions, split by topic
    memory/
      current-state.md
      decisions/
    sessions/
      2026-09-22-billing-split.md

Claude Code reads CLAUDE.md files. Many other coding agents read AGENTS.md. If you use more than one assistant, keep both short and consistent, or point one at the other. The guide on writing CLAUDE.md and AGENTS.md covers what to put in them.

Two practical points:

  • Do not rely on a global or per-user instructions file for project facts. It stays on one machine. Project facts belong in the project.
  • Keep instructions short and point to memory. One line such as "Read .prjcontext/memory/current-state.md before starting" does more than a long file nobody updates.

Save the session that holds the thread

Some sessions contain reasoning you cannot rebuild from the code: why a test is skipped, which library failed and how, the order of steps you agreed on. When you switch machines in the middle of that work, save that session with the project.

You do not need every session. Keep the one that holds the current plan. Export or copy it as text, trim the noise (long tool output, repeated file dumps), and save it under .prjcontext/sessions/ with a date and a topic in the name.

Then add one line to your handoff note: "Full reasoning in sessions/2026-09-22-billing-split.md." Your next session can read the summary first and the transcript only when needed.

For a fuller method, see which AI coding sessions are worth keeping.

What must not travel: secrets and machine config

Moving context is good. Moving secrets with it is not. Before you copy or sync anything, check these:

  • .env files stay behind. Commit a .env.example with the variable names and fake values. On the new machine, fill in real values from your password manager or your team's secret store.
  • Keys and credential folders stay behind. SSH keys, cloud credentials and API tokens belong to the machine or to your account, not to the project.
  • Transcripts can hold secrets too. If you pasted a token into a session, or the assistant printed an environment variable, remove it before you save the transcript. Search the file for key, token, secret and password before it leaves your machine.
  • Machine paths are noise. Absolute paths like /Users/you/... in notes confuse the next session. Use paths relative to the project root.

The article on keeping secrets out of AI context goes deeper on transcripts and key files.

On the new machine: a start-up routine

When you sit down at the other machine, run the same short routine every time:

  1. Get the code and the context. Pull or clone the project, including the context folder.
  2. Recreate the environment. Copy .env.example to .env and fill it in. Install dependencies.
  3. Run the tests once. You want to know the starting state before the assistant changes anything.
  4. Brief the assistant from files, not from memory. Start the session with a prompt like this:
Read CLAUDE.md and .prjcontext/memory/current-state.md.
Summarise where the work stands, what is decided, and what is next.
Do not change any files yet.
  1. Check the summary. If the assistant gets something wrong, fix the note, not just the chat. The next machine will need the fix too.
  2. Update the note when you stop. The routine only works if the last machine always leaves a current note.

This takes a few minutes. It replaces the long re-explaining at the start of every session, and it catches the "we already rejected that" moment before it costs you an afternoon.

How PrjLab handles this

We built PrjLab so the project and its context move as one piece. Put instructions in .prjcontext/instructions/ (or keep CLAUDE.md and AGENTS.md at the root), notes and decisions in .prjcontext/memory/, and the sessions you choose to keep in .prjcontext/sessions/. Run prj status to see what would be captured, then prj push on the old machine. On the new one, prj clone brings down the files and the context together, and later prj pull updates that copy without overwriting local edits: conflicting files are reported, not replaced. The CLI skips obvious secrets such as .env files, key files and credential folders, but it is a safety net, not a full secret scanner, so you still review prj status before you push. PrjLab sits beside git; it does not replace it. The getting-started guide walks through each command.

Frequently asked questions

Can I just commit my notes and sessions to git instead? Yes, if your team is fine with them in the code history. Many people prefer to keep sessions and personal notes out of the main repository, which is why a separate context folder helps either way.

Should I sync my assistant's whole history folder between machines? No. It mixes projects, may hold secrets and personal data, and is hard to review. Save the few sessions that matter into the project instead.

How long should the handoff note be? Short enough to read in two minutes. If it grows past a page, move lasting decisions into their own records and keep the note about the current state only.

What if I forget to write the note? Ask the assistant on the old machine to draft it from the session before you close it, then read and correct it. A corrected draft is far better than nothing.

Ready to try it on your own project? Follow the getting-started guide.

#ai coding#workflow#project memory#handoff#multiple machines

Share on XShare on LinkedIn