ag-syncro

"git for agent memory"

When switching between AI agents — Claude Code, Codex, Gemini, Cursor — the next agent starts with zero context. You lose time re-explaining the project, the stack, what's done, and what's next.

ag-syncro fixes this. It maintains a .agent/ folder in your project that any agent can read instantly. One command to sync out, one command to sync in. No copy-pasting, no re-explaining.

Install

npm install -g ag-syncro

Quickstart

cd my-project
ag-syncro init       # sets up .agent/ in your project
ag-syncro capture    # tell your agent to run this — it fills .agent/ automatically

From then on, every time you switch agents:

ag-syncro sync       # outputs full context — agent reads it and picks up instantly

How it works

ag-syncro init scaffolds a .agent/ folder into your project:

.agent/
├── AGENT.md        ← universal instructions for any AI agent
├── state.json      ← structured state: last agent, completed, in-progress, next steps
├── log.md          ← append-only session history
├── HANDOFF.md      ← mid-flight notes when work is interrupted
└── stack/          ← optional stack reference files

AGENT.md instructs the agent to:

• Run ag-syncro sync at the start of every session to load context
• Update state.json and log.md automatically at the end of every session

The developer never touches .agent/ manually. The agent handles it.

Commands

ag-syncro init

Scaffolds .agent/ into the current project. Safe to re-run — never overwrites existing files.

cd my-project
ag-syncro init

ag-syncro capture

For first-time setup on an existing project. Outputs a prompt that tells the current agent to scan the project and fill .agent/ from scratch.

ag-syncro capture

• Agent has terminal access (Claude Code, Codex): tell it to run ag-syncro capture directly — no copy-pasting needed
• Web-based agent (ChatGPT, Claude.ai): run it yourself and paste the output

ag-syncro sync

The main command. Reads all .agent/ files and outputs a universal context block ready for any agent.

ag-syncro sync

• Agent has terminal access: the agent runs this itself at session start — fully automatic
• Web-based agent: run it and paste the output as your first message

Works with any agent — Claude Code, Codex, Gemini, ChatGPT, Cursor, or anything else.

ag-syncro status

Prints .agent/state.json in human-readable form.

ag-syncro status

ag-syncro handoff

Generates a checklist prompt for the current agent to update .agent/ before ending a session.

ag-syncro handoff

ag-syncro help

Prints all commands and descriptions.

ag-syncro help

ag-syncro -v

Prints the current version.

ag-syncro -v

Full workflow example

Claude Code hits rate limit, switching to Codex:

1. ag-syncro sync          ← run in terminal (or tell Claude to run it)
2. Open Codex
3. Tell Codex: run ag-syncro sync
4. Codex reads the output — full context loaded, picks up instantly

Zero re-explaining. Zero copy-pasting. Zero lost context.

The .agent/ folder

| File | Purpose | |------|---------| | AGENT.md | Universal agent instructions — works with any AI | | state.json | Last agent, stack, completed, in-progress, next steps, decisions | | log.md | Append-only session history, never overwritten | | HANDOFF.md | Mid-flight notes when work is interrupted | | stack/ | Optional stack reference files (e.g. nextjs.md, laravel.md) |

state.json schema

{
  "last_updated": "2026-04-02T00:00:00Z",
  "last_agent": "Claude Code",
  "project": "my-project",
  "stack": ["Next.js", "Tailwind", "Supabase"],
  "completed": ["built auth flow", "set up database schema"],
  "in_progress": ["dashboard page"],
  "next": ["add chart components", "connect to API"],
  "decisions": ["using Supabase over PlanetScale: easier auth integration"]
}

Stack templates

Stack-specific reference files are included for common setups. Copy the relevant one into .agent/stack/ and the agent will use it for context:

cp node_modules/ag-syncro/templates/stack/nextjs.md .agent/stack/

Available: nextjs.md, laravel.md, flutter.md, wordpress.md, unity.md

.gitignore

Add .agent/ to keep context local (recommended for personal projects):

.agent/

Or commit it to share agent context across a team.

License

MIT