Adapt Agent Backup

Adapt Agent Backup

Use this skill when adding support for a new Code Agent source to context-harness.

First Read

Before editing, read:

• docs/agent-backup-adapter-architecture.md
• Existing collectors in context_harness/collectors/
• Existing tests for Codex and Claude Code in tests/

Workflow

1. Identify the source id.

• Use lowercase kebab-case, for example my-agent.
• Infer the target Agent from the current runtime, app name, CLI name, repository metadata, process environment, or user prompt.
• Derive the id from that Agent name unless the user explicitly provides one.
• Ask the user for the target Agent only if it cannot be inferred with reasonable confidence.
• Use the same id in config, CLI, output directories, state keys, tests, and docs.

1. Check whether the source is already supported.

• Search for the source id and common aliases in context_harness/, tests/, skills/, README.md, and README.zh-CN.md.
• Inspect context_harness/cli.py sync choices, context_harness/config.py, context_harness/init.py, context_harness/collectors/, and context_harness/hooks/.
• If support is complete, do not add a duplicate adapter. Instead, verify it with existing tests or a smoke command, then report that the source is already supported.
• If support is partial or broken, repair only the missing or failing pieces and preserve the existing source id and archive/state compatibility.

1. Inspect the target Agent's local transcript format.

• Find default transcript paths.
• Identify session id, title, timestamps, roles, user messages, assistant messages, tool/noise events, and internal meta events.
• Check whether the Agent has a reliable stop/session hook. If not, implement manual sync only.
• Use synthetic or anonymized fixtures only.

1. Add config and initialization.

• Update context_harness/config.py with a new source in AppConfig and load_config.
• Update context_harness/init.py with default config and conversations/ directory creation.

1. Add a collector.

• Create context_harness/collectors/.py.
• Parse raw transcript files into Conversation and Message.
• Ignore bad JSON lines, empty messages, tools, and internal metadata.
• Return None for sessions with no user-visible conversation.
• Reuse render_conversation, read_state, write_state, and the existing SyncResult pattern.
• Support latest, all_sessions, and session_path.

1. Register CLI commands.

• Add the source to sync choices in context_harness/cli.py.
• Dispatch to sync_.
• Respect enabled = false with _disabled_result.

1. Add hooks only when reliable.

• Create context_harness/hooks/.py only if the Agent has a stable hook/config mechanism.
• Hook commands should call sync --hook-stdin.
• Preserve unrelated user settings and make hook installation idempotent.
• Register hook install support in context_harness/cli.py.

1. Update docs and skills.

• Update README.md and README.zh-CN.md.
• Add the source to the supported local AI coding assistants list in both README files.
• Prefer the target Agent's official product/docs URL for the link.
• Prefer an official favicon/logo URL from the Agent's website or docs for the icon; if no reliable official icon URL exists, use a plain text link instead of adding an unofficial asset.
• Update skills/init-context/SKILL.md and skills/sync-conversations/SKILL.md.
• Keep skills as workflow instructions; keep behavior in the CLI.

1. Add focused tests.

• Add fixtures under tests/fixtures/.
• Cover config defaults/custom paths, init directories/default config, collector archive output, skipped unchanged archives, missing source directory, latest mtime behavior, hook session_path override, noise filtering, bad JSON tolerance, filename stability, CLI sync, disabled source behavior, and hook idempotence if hooks are implemented.

1. Verify.

• Run uv sync if dependencies are not installed.
• Run uv run pytest.
• Manually smoke test uv run context-harness --context-home sync --latest 1 when a fixture or local sample is available.
• Keep changes small and complete; do not refactor unrelated modules.

1. Prepare the PR for automated review.

• Add label agent-backup-adapter. This label marks the PR as an Agent backup adapter and allows repository automation to run adapter-specific checks.
• Add label ai-review only when an explicit Claude AI review is desired. This is a manual shortcut label and does not replace agent-backup-adapter.
• Include Source id: in the PR body.
• Include transcript path/format assumptions, hook support status, verification commands, and remaining risks.
• Optional AI review enhancement: if the repository has Codex GitHub integration enabled, comment @codex review; if Claude Code GitHub Actions is enabled, either add label ai-review or comment @claude review this adapter PR against the adapt-agent-backup checklist. Any one of these is acceptable as an extra AI review signal.

PR Checklist

• The adapter produces Markdown archives in context_home/conversations//.
• The adapter writes incremental state to context_home/state/-sync-state.json.
• README supported-Agent lists, examples, default config, skills, CLI choices, and tests all use the same source id.
• Real user transcripts, memory, logs, state, and private machine config are not committed.
• PR has label agent-backup-adapter, and its body includes Source id: .
• PR has label ai-review only when a manual Claude AI review should be requested.
• PR description states transcript format assumptions, hook support status, commands run, and remaining risks.
• The diff avoids unrelated rewrites and leaves existing behavior intact outside the new adapter path.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yinjialu
• Source: yinjialu/context-harness
• License: MIT

Install and usage instructions live in the source repository linked above.