Switching AI coding tools is often less painful than explaining the same project all over again. Why did the last session choose this architecture? Which branch is in progress? Which tests passed, which PR still needs review, and what was the previous agent actually authorized to change?

I started moving that fragile project state out of chat transcripts and into GitHub. Codex, Claude Code, Cursor, or ChatGPT in a browser can each be an entry point: first read the repository’s task and version, then work on a separate branch if the client has write access—or leave a review if it only has read access.

I call this GitHub-first: AI tools are replaceable; engineering state should not disappear with a chat window. I don’t need a permanently running coordination bot just to remember a task, and I can pass the next step along from a phone.

Conversation memory is not engineering context

Long-running projects cross days and tools. Agent B does not know why A rejected an earlier design. A new chat sees green CI on an old commit and assumes the current HEAD is green. Two people edit the same file, each believing they own the task. Pasting ten pages of context into the next prompt helps for a moment but makes the project more dependent on one vendor’s session history.

Separate chat memory from engineering context. GitHub doesn’t transfer a model’s internal reasoning or private conversation history. It can persist four kinds of facts that the next tool can read, verify, and update:

• Project rules: AGENTS.md, README, and architecture notes. Not every client loads AGENTS.md automatically, so ask explicitly when necessary.
• Task identity: Issue, task ID, plan, owner, checkpoint, completed work, and outstanding verification.
• Code version: main, feature branches, commit and Git Blob SHAs. Each task must identify its actual working branch.
• Review and acceptance: PR diff, review comments, ACK, CI runs for the exact HEAD, and merge or deployment records.

This does not require one enormous JSON database. Git already tracks code, Issues and PRs already hold discussions, and an optional checkpoint fills in “what comes next?” Never use the repo as a secrets store, fast-changing distributed lock, or temporary model-context cache.

Instead of copying ten screens of old chat, this is the short handoff prompt I give a new session:

You are the developer for this task. Recover project state read-only first.
Repository: OWNER/REPO
Task: Issue #N, linked PR #M, task ID TASK_ID

Read repository rules, the plan, checkpoint, current feature-branch HEAD,
PR diff, the latest applicable review comments, and checks for that HEAD.
Explain the authorized actions, verified work, and remaining gates.
Stop and report if the branch moved, permissions differ, or orders conflict.
Do not merge, deploy, or change production settings without separate approval.

Solo developers can start smaller: one README or AGENTS.md, an Issue or PR, and a few recent commits are enough to try a handoff. Add checkpoint and Order/ACK validation only when work spans sessions, multiple writers, or independent review.

One GitHub state layer, multiple AI tools and branches

The architecture is simple enough to draw:

Phone / browser / local IDE / cloud coding agent
                       |
             Read GitHub task facts
                       |
       AGENTS.md · Issue · plan · checkpoint
                  branch · PR
                       |
              Check permission scope
                       |
         Feature branch A     Fix branch B
                  |                |
                commit           commit
                  |                |
                 PR A             PR B
                     \           /
                   review + CI per HEAD
                           |
                  Human approval to merge
                           |
                          main

These entry points do not automatically have identical GitHub permissions. Some integrations can search or read a repository; some coding agents can edit files and open a branch or PR in their own runtime. As of October 2026, this is an explanation of different capability types, not a claim that I tested every named product’s current permissions. Before using one, check the actual read, write, comment, merge, and deploy grants.

Branches are the natural boundary for parallel developers or agents. A cloud agent can work on feature A, a browser session can suggest documentation changes, and local Codex can work on a fix branch. Their work meets in PRs rather than overwriting a shared working tree.

Different branches do not prevent logical conflicts. Two branches may both change an API or dependency. Prefer one actual writer per task branch, then review the shared base, affected files, current CI and integration tests before merging. GitHub’s pull-request documentation covers this workflow; protected branches can enforce reviews and checks.

Git Worktree solves a related but different problem: multiple local directories and processes. My Git Worktree guide covers that side. Here the question is how different AI tools claim the same GitHub task and bring their changes back together.

Cross-tool handoff: verify the Issue, branch and PR first

A prompt is only a starting address. The receiving tool still needs real files to read. Can it answer which HEAD is current, what the last agent actually delivered, and who may write next?

For a lightweight setup, put a small AGENTS.md in the root. Keep it a map to your real project instructions:

# AGENTS.md

- Stack and architecture: see README.md and docs/architecture.md
- Install and test: follow the current commands in README.md
- Task entry points: GitHub Issue and linked PR
- Optional state: tasks/<TASK_ID>/checkpoint.json
- Before editing: verify task ID, branch, and live HEAD
- Prefer one writer for each feature branch
- Merges and deployments need separate approval

The checkpoint.json records milestones that the code alone cannot explain. These key names come from a real project checkpoint, but all identifiers here are replaceable placeholders:

{
  "task_id": "TASK_ID",
  "phase": "P2",
  "status": "IN_PROGRESS",
  "branch": "feat/TASK_ID",
  "commit_sha": "REPLACE_WITH_LAST_VERIFIED_40_HEX_SHA",
  "pr": "https://github.com/OWNER/REPO/pull/N",
  "verification": { "merge": { "status": "NOT_AUTHORIZED" } },
  "next_action": "Read current HEAD and review comments before resuming"
}

This is a starting example, not my original private checkpoint. Do not update it after every commit just because a JSON file exists. For a small task, an Issue or PR is enough; I update a checkpoint at an actual handoff, verification milestone, or blocker.

There is an easily missed trap: checkpoint.commit_sha is the last verified code commit, not necessarily the commit containing the checkpoint file and never automatically the live HEAD. If code was verified at commit A and checkpoint was committed at B, the file can point to A. It cannot know B’s own future hash before B exists. Nor is there a fixed one-commit offset; more commits can follow.

A new agent must fetch the live branch HEAD from GitHub and reconcile later changes with the recorded baseline. Different SHAs alone are not necessarily an error. The ACK fields observed_head_sha and new_head_sha describe the reviewed old version and the developer’s new version. An Order bound to an obsolete HEAD is a separate stale-order decision.

AGENTS.md gives rules, Issue/PR preserve discussion and review, and checkpoint summarizes optional progress. Some clients require an explicit instruction to read AGENTS.md.

I released the stricter handoff protocol from my own projects as open source. You do not need it for the lightweight method; if you want to inspect how Order/ACK records bind to a HEAD, reject obsolete instructions and validate repeated handoffs, the source and offline tests are available:

vxime/conversation-memory-hub

The repository contains the protocol, validators, and examples. It does not mirror your project’s state into a hosted service or automatically wake up other AI chats. The actual tasks and PRs remain in your own GitHub repository.

A real PR: FIX_REQUIRED, ACK and an independent re-review

An architecture diagram can be comforting: two AIs both reply “got it”, so we assume the handoff worked. I checked a real documentation PR from a private project. Agent B raised two issues, agent A revised the plan, and B inspected the new version before allowing the work to advance.

First, the uppercase words are my project’s comment protocol, not native GitHub PR states. FIX_REQUIRED means “fix these findings”, ACK is the developer’s acknowledgement and new version, ADVANCE is the reviewer’s decision after checking the new HEAD. STALE_ORDER, explained below, means an instruction no longer matches the branch version.

The PR updated a read-only Runner audit plan; it did not install a Runner. The important F-001 finding was that the proposed audit checked for dangerous GitHub Actions comment triggers but its command only listed workflow file names:

# Original plan: names only; the YAML triggers remain invisible.
gh api "repos/OWNER/REPO/contents/.github/workflows" --jq '.[].name'

That cannot reveal whether a workflow’s top-level on: includes issue_comment. F-002 was a wrong document-section reference. The revised plan pinned an audit SHA, read the actual YAML trigger blocks and rechecked whether HEAD moved. I compared the before and after documents. GitHub’s Actions event reference explains the trigger concern.

A then posted an ACK and new HEAD in the original PR. B re-read that HEAD, verified both fixes, and only then issued ADVANCE. This is a human-directed exchange between two AI sessions, not an automatic cross-chat wakeup and not an installed Actions gate or local Git hook. Ordinary PR comments and a pinned HEAD are enough for a simple handoff; structured ACK validation is an optional stricter layer.

Here are the useful fields from the real ACK comment, with private IDs and SHAs replaced:

{
  "protocol": "ai-supervisor/ack/v1",
  "task_id": "TASK_ID",
  "order_id": "REPLACE_WITH_ORDER_ID",
  "decision_received": "FIX_REQUIRED",
  "observed_head_sha": "REPLACE_WITH_OLD_HEAD",
  "new_head_sha": "REPLACE_WITH_NEW_HEAD",
  "executed": [
    "F-001: Inspect workflow triggers at a pinned SHA",
    "F-002: Correct the audit plan's section reference"
  ]
}

This is a shortened excerpt; the original protocol includes other fields and integrity checks. The important part is that A identifies the old HEAD tied to B’s finding and the new HEAD it handed back. B can review the actual new version rather than trusting “done”.

That PR only changed documentation. There was no successful CI result for the relevant HEAD and no production VPS audit. What I can verify is a traceable review-and-revision handoff, not a fully autonomous system.

STALE_ORDER: why instructions tied to an old HEAD must stop

An Order is a structured instruction B writes in an Issue/PR comment: it binds task ID, target branch, observed HEAD, findings, and permitted or forbidden actions. The order_id in the ACK refers back to that instruction.

In a separate negative trial, an Order in a test Issue was tied to an older main HEAD. The repository moved forward. When A recovered the old Order it should return STALE_ORDER rather than write code under outdated instructions.

I checked the archived Order, later HEAD, and the decideResume() staleness check in the source. At the time, A reported that it had stopped; however the stop report was relayed by a person, not posted by A as an independent GitHub ACK. It was a useful negative rehearsal, not end-to-end validation across every AI client.

The practical rule is small: B binds task, branch, version and permitted actions; A re-fetches live HEAD before executing. If the target branch has moved, A stops and B reviews the new version. A formerly correct instruction is still the wrong instruction for different code.

That is why independent review matters to me. An agent producing a plausible diff and another session verifying a fix against the actual new HEAD are two distinct events. For broader multi-agent owner and state design, see my AI Agent orchestration article.

Working from a phone doesn’t make GitHub a free computer

The practical convenience is that I no longer need to keep a particular Mac awake or run a resident coordinator just to remember a task. With a GitHub-capable client, I can check the PR, read a review and hand off the next action from a phone. Editing, building and testing still happen in a properly authorized cloud agent, runner, or local environment.

There are two separate cost questions: repeating context and maintaining a dedicated bot may waste my time, but model inference, Chat/Codex/API quotas and CI have their own costs. I have not run a comparable Token-cost experiment, so I will not claim a made-up percentage saved.

My blog already has a GitHub Actions → self-hosted Runner deployment path; my cross-device deployment article explains that later stage. This article is about an earlier one: how to tell whether someone on another tool or device is continuing the same task at all.

For a low-risk one-file change, one agent and one branch may be enough. As the project spans days, tools and people, explicit checkpoints, branch ownership, independent review and permission boundaries become more valuable. What appeals to me about GitHub-first isn’t the fantasy that AI tools share a memory: it’s that the engineering facts remain where the next participant can find them.