# Session Handoff MCP

[![CI](https://github.com/Dev-Russo/session-handoff-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Dev-Russo/session-handoff-mcp/actions/workflows/ci.yml)

Session Handoff MCP preserva continuidade entre sessões de coding agents por meio de checkpoints locais, estruturados e legíveis. A V1 é focada exclusivamente no fluxo `checkpoint → clear → resume` entre Claude Code e Codex.

> Estado atual: milestones 1–10 concluídos. O servidor MCP cobre criação, retomada e sincronização Git opcional, com integrações guiadas para Claude Code e Codex, exemplo público fictício e demonstração automatizada. O próximo milestone é o uso real por duas semanas antes da V2.

## Requisitos

- Node.js 24 ou superior
- pnpm 10
- Git opcional apenas para o repositório privado de dados

## Desenvolvimento

```bash
pnpm install
pnpm check
pnpm dev init --help
```

## Demonstração

Para executar localmente o fluxo completo com dois clientes MCP independentes e storage temporário:

```bash
pnpm demo
```

A demonstração compila o servidor, cria um checkpoint como Claude Code, retoma como Codex, salva o estado atualizado e o retoma novamente como Claude Code. Ela funciona offline, não altera configurações pessoais e remove os dados temporários ao terminar.

O [roteiro completo](examples/README.md) também descreve a validação manual nos clientes reais. O [repositório fictício](examples/fake-memory-repo/) contém um checkpoint canônico que pode ser inspecionado sem expor dados privados.

## Inicialização

```bash
pnpm build
pnpm dev init
```

Para automação:

```bash
session-handoff init \
  --non-interactive \
  --data-dir /caminho/para/agent-memory-data \
  --json
```

O comando cria a configuração e a pasta `projects/`, verifica permissões e detecta Git. Ele nunca executa `git init`. Um repositório Git pai é ignorado por padrão.

O servidor exige uma configuração válida antes de iniciar. O loader aceita somente caminhos absolutos ou iniciados por `~/`, rejeita chaves YAML desconhecidas e valida `data_repo_path/projects` sem modificar o storage.

Overrides disponíveis:

```text
SESSION_HANDOFF_CONFIG
SESSION_HANDOFF_DATA_REPO
```

## Registro MCP

```bash
codex mcp add session-handoff -- session-handoff mcp
claude mcp add --transport stdio --scope user session-handoff -- session-handoff mcp
```

Para instalar a skill pessoal e os hooks opcionais de retomada automática, consulte [integrations/claude-code/README.md](integrations/claude-code/README.md). A instalação é manual e nunca substitui configurações existentes do Claude Code.

Para adicionar as instruções persistentes do workflow ao Codex, consulte [integrations/codex/README.md](integrations/codex/README.md). O escopo recomendado é global pessoal em `~/.codex/AGENTS.md`.

## Criando um checkpoint

Depois de registrar o servidor, o cliente MCP pode chamar `memory_checkpoint` com um snapshot completo:

```json
{
  "project_key": "meu-projeto",
  "objective": "Entregar a funcionalidade atual.",
  "state_summary": "Implementação consolidada até este ponto.",
  "completed": ["Contrato principal implementado."],
  "decisions": [],
  "pending": ["Adicionar o teste de integração."],
  "next_step": "Implementar e executar o teste de integração.",
  "validation": [],
  "files_touched": ["src/example.ts"]
}
```

O checkpoint é salvo em `projects/<project_id>/checkpoints/` antes de qualquer operação Git. Quando habilitado com segurança, o adapter adiciona e commita somente o checkpoint recém-criado; push é controlado por `auto_push` ou `sync_mode: pull-push`. Falhas e contenção do lock são reportadas em `git_status` e warnings, sem invalidar o arquivo local.

## Retomando uma sessão

No início de uma nova sessão, chame `memory_resume` usando a mesma `project_key`, quando ela tiver sido adotada:

```json
{
  "project_key": "meu-projeto",
  "sync": "none"
}
```

O resultado contém o checkpoint válido mais recente como briefing compacto, além de `truncated`, `truncated_fields` e uma estimativa de tokens. Checkpoints corrompidos são ignorados em favor do candidato válido anterior.

Com `sync: "pull"`, o servidor tenta `git pull --rebase` antes da leitura. Em falha de rede, autenticação, timeout ou conflito, usa a cópia local e retorna `offline_or_failed`, `data_may_be_stale: true` e um warning explícito. Um `sync: "none"` explícito sempre desabilita o pull naquela chamada.

Consulte [docs/SDD.md](docs/SDD.md) para o contrato normativo da V1.1.

## Validação

```bash
pnpm check
pnpm test:coverage
npm pack --dry-run
```

Os testes automatizados cobrem o formato compartilhado e o handoff entre clientes MCP. O aceite nos aplicativos Claude Code e Codex reais, o fluxo em duas máquinas e o período de uso de duas semanas permanecem validações operacionais explícitas.