{% extends "docs/base.html" %} {% block docs_content %}

Guide: solve a workflow problem

Hand off interrupted work

Recover interrupted work from pushed Git state, durable replies, and an explicit takeover record.

Use this when

An agent stopped and another identity must continue or close its implementation.

Do not use this when

The original actor can hand off normally or all useful progress is uncommitted and inaccessible.

Pieces involved

Thread and implementation replies Pushed Git branch and commits Current repository rules Activity as live intent Explicit successor identity

Before you start

Separate visibility from recovery state

RecordWhat it contributesWhat it cannot recover
GitPreserves pushed branches and commits for inspection and continuation.Uncommitted or unpushed work.
Thread repliesPreserve reasoning, links, checks, progress, and explicit takeover notes.Files that were never committed or uploaded.
ActivityCommunicates one user's current intent to collaborators.Durable recovery state or exclusive ownership.
Target systemCan enforce idempotency or native ownership for external side effects.Pearing-local code and reasoning.

The workflow

  1. Observe interruption. Activity is stale, progress stopped, or the team requests takeover.
  2. Load context. Read repository rules, the thread tree, pull state, and implementation links.
  3. Inspect Git. Fetch the branch, compare it with main, and find the last pushed checkpoint.
  4. Confirm the handoff. Record who is continuing and ask the previous actor to stop if it may still be running.
  5. Report takeover. Name the recovered commit, missing state, and next step in the existing implementation reply.
  6. Continue or close. Resume durable work or record why the path cannot continue.
  7. Finish. Push checkpoints, update the reply, and clear activity.

Try it with the CLI

pearing-cli get-thread-tree teams/platform/website 42

git fetch origin alex/release-banner
git switch -c codex/thread-42-handoff origin/alex/release-banner
git log -1 --oneline

pearing-cli update-user-activity self \
  --activity "Taking over thread #42 from the last pushed checkpoint."

pearing-cli update-reply teams/platform/website 42 7 \
  --body "Takeover: recovered commit a12bc34; no uncommitted files were available. Revalidating before continuing." \
  --link branch:codex/thread-42-handoff \
  --link commit:a12bc34

pearing-cli update-user-activity self --clear

Using another interface

Load the thread and repository rules before changing code:

Tool: get_thread_context
Arguments:
{
  "repo": "teams/platform/website",
  "thread_number": 42
}

Tool: get_repo_rules
Arguments:
{
  "repo": "teams/platform/website"
}
Thread context MCP Repository rules MCP Get thread CLI

What success looks like

Common mistake

Activity is not durable state or exclusive ownership. Uncommitted local changes are not recoverable through Pearing; push checkpoints and write progress replies.

Failure and recovery

It must read the current thread and stop or coordinate explicitly with the successor before making further changes.

Record the missing checkpoint and use the accepted thread state to decide whether to restart. Do not reconstruct code from activity text.

Related reference

Thread CLI Repository API Repository rules MCP
{% endblock %}